@capra/core 1.5.3 → 1.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.cjs +42 -78
- package/dist/index.d.cts +8 -2
- package/dist/index.d.mts +8 -2
- package/dist/index.mjs +42 -78
- package/dist/style.css +62 -32
- package/docs/conventions--docs.md +186 -0
- package/docs/core-alert--design.md +110 -0
- package/docs/core-alert--usage.md +13 -0
- package/docs/core-anchor--design.md +39 -0
- package/docs/core-anchor--usage.md +39 -0
- package/docs/core-autocompletefield--design.md +91 -0
- package/docs/core-autocompletefield--usage.md +18 -0
- package/docs/core-badge--design.md +70 -0
- package/docs/core-badge--usage.md +13 -0
- package/docs/core-breadcrumbs--design.md +65 -0
- package/docs/core-breadcrumbs--usage.md +16 -0
- package/docs/core-button--design.md +97 -0
- package/docs/core-button--usage.md +17 -0
- package/docs/core-buttonlink--design.md +7 -0
- package/docs/core-buttonlink--usage.md +24 -0
- package/docs/core-card--design.md +100 -0
- package/docs/core-card--usage.md +5 -0
- package/docs/core-checkbox--design.md +66 -0
- package/docs/core-checkbox--usage.md +34 -0
- package/docs/core-collapse--design.md +28 -0
- package/docs/core-collapse--usage.md +20 -0
- package/docs/core-datepickerfield--design.md +71 -0
- package/docs/core-datepickerfield--usage.md +57 -0
- package/docs/core-daterangepickerfield--design.md +76 -0
- package/docs/core-daterangepickerfield--usage.md +62 -0
- package/docs/core-divider--design.md +35 -0
- package/docs/core-divider--usage.md +8 -0
- package/docs/core-drawer--design.md +87 -0
- package/docs/core-drawer--usage.md +9 -0
- package/docs/core-emptystate--design.md +45 -0
- package/docs/core-emptystate--usage.md +13 -0
- package/docs/core-helpertext--design.md +30 -0
- package/docs/core-helpertext--usage.md +11 -0
- package/docs/core-iconbutton--design.md +87 -0
- package/docs/core-iconbutton--usage.md +15 -0
- package/docs/core-inputrow--design.md +85 -0
- package/docs/core-inputrow--usage.md +6 -0
- package/docs/core-label--design.md +27 -0
- package/docs/core-label--usage.md +17 -0
- package/docs/core-link--design.md +58 -0
- package/docs/core-link--usage.md +16 -0
- package/docs/core-listitem--design.md +70 -0
- package/docs/core-listitem--usage.md +6 -0
- package/docs/core-menu--design.md +106 -0
- package/docs/core-menu--usage.md +16 -0
- package/docs/core-modal--design.md +39 -0
- package/docs/core-modal--usage.md +11 -0
- package/docs/core-numberfield--design.md +12 -0
- package/docs/core-numberfield--usage.md +14 -0
- package/docs/core-pagination--design.md +30 -0
- package/docs/core-pagination--usage.md +13 -0
- package/docs/core-passwordfield--design.md +7 -0
- package/docs/core-passwordfield--usage.md +3 -0
- package/docs/core-pill--design.md +94 -0
- package/docs/core-pill--usage.md +10 -0
- package/docs/core-popover--design.md +25 -0
- package/docs/core-popover--usage.md +8 -0
- package/docs/core-radio--design.md +39 -0
- package/docs/core-radio--usage.md +8 -0
- package/docs/core-radiogroup--design.md +5 -0
- package/docs/core-radiogroup--usage.md +12 -0
- package/docs/core-radiotile--design.md +5 -0
- package/docs/core-radiotile--usage.md +10 -0
- package/docs/core-ribbon--design.md +39 -0
- package/docs/core-ribbon--usage.md +12 -0
- package/docs/core-skeleton--design.md +88 -0
- package/docs/core-skeleton--usage.md +13 -0
- package/docs/core-skeletongroup--design.md +50 -0
- package/docs/core-skeletongroup--usage.md +10 -0
- package/docs/core-spinner--design.md +99 -0
- package/docs/core-spinner--usage.md +11 -0
- package/docs/core-switch--design.md +145 -0
- package/docs/core-switch--usage.md +8 -0
- package/docs/core-tabnav--design.md +77 -0
- package/docs/core-tabnav--usage.md +63 -0
- package/docs/core-tag--design.md +21 -0
- package/docs/core-tag--usage.md +11 -0
- package/docs/core-text--design.md +32 -0
- package/docs/core-text--usage.md +10 -0
- package/docs/core-textarea--design.md +74 -0
- package/docs/core-textarea--usage.md +18 -0
- package/docs/core-textfield--design.md +81 -0
- package/docs/core-textfield--usage.md +12 -0
- package/docs/core-textinput--design.md +72 -0
- package/docs/core-textinput--usage.md +19 -0
- package/docs/core-toast--design.md +100 -0
- package/docs/core-toast--usage.md +11 -0
- package/docs/core-tooltip--design.md +61 -0
- package/docs/core-tooltip--usage.md +48 -0
- package/docs/core-topnav--design.md +75 -0
- package/docs/core-topnav--usage.md +6 -0
- package/docs/core-verticalnavigation--design.md +31 -0
- package/docs/core-verticalnavigation--usage.md +17 -0
- package/docs/core-visuallyhidden--design.md +87 -0
- package/docs/core-visuallyhidden--usage.md +35 -0
- package/docs/history-changelogs-capra-core--docs.md +60 -0
- package/docs/index.md +110 -0
- package/docs/using-capra--docs.md +39 -0
- package/package.json +5 -4
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# Core/Toast - Design
|
|
2
|
+
|
|
3
|
+
Renders a toast inline for documentation/preview. Not for use in production.
|
|
4
|
+
|
|
5
|
+
## Anatomy
|
|
6
|
+
|
|
7
|
+
### Status icon
|
|
8
|
+
|
|
9
|
+
<span>
|
|
10
|
+
Indicates the type of message (info, success, warning, error)
|
|
11
|
+
</span>
|
|
12
|
+
|
|
13
|
+
### Body
|
|
14
|
+
|
|
15
|
+
<span>
|
|
16
|
+
The message text informing the user what occurred
|
|
17
|
+
</span>
|
|
18
|
+
|
|
19
|
+
### Dismiss
|
|
20
|
+
|
|
21
|
+
<span>
|
|
22
|
+
Close button to manually dismiss the toast
|
|
23
|
+
</span>
|
|
24
|
+
|
|
25
|
+
### Actions
|
|
26
|
+
|
|
27
|
+
<span>
|
|
28
|
+
Optional action button relating to the notification (e.g. "Try again", "Undo")
|
|
29
|
+
</span>
|
|
30
|
+
|
|
31
|
+
## Properties
|
|
32
|
+
|
|
33
|
+
### Type
|
|
34
|
+
|
|
35
|
+
All toasts have a status of: information, attention, warning, success, and highlight. Choose the status depending on the type of message.
|
|
36
|
+
|
|
37
|
+
### Body
|
|
38
|
+
|
|
39
|
+
All toasts have body text, informing the user that something has occurred. The message should be as concise as possible, if a longer message is needed, consider an Alert Banner or Dialog.
|
|
40
|
+
|
|
41
|
+
### Actions
|
|
42
|
+
|
|
43
|
+
Toasts can have up to two action buttons, relating directly to the action taken that resulted in the notification. Examples include a link to a relevant list, or an action to try a failed submit.
|
|
44
|
+
|
|
45
|
+
## Behavior
|
|
46
|
+
|
|
47
|
+
### Timeout
|
|
48
|
+
|
|
49
|
+
Toasts automatically close 6 seconds after they have fully loaded. The timer is paused if focus is brought into the toast by the user.
|
|
50
|
+
|
|
51
|
+
### Placement
|
|
52
|
+
|
|
53
|
+
Toasts appear in the right corner of the application—either top-right (default) or bottom-right. Use the <code>position</code> option when calling the Toast API to choose placement.
|
|
54
|
+
|
|
55
|
+
### Width
|
|
56
|
+
|
|
57
|
+
Toasts have a flexible width that sizes to content, with a minimum of 360px and maximum of 480px.
|
|
58
|
+
|
|
59
|
+
### Overflow
|
|
60
|
+
|
|
61
|
+
Long messages wrap within the toast width (360-480px). Craft messages to take up no more than two lines.
|
|
62
|
+
|
|
63
|
+
## Best Practices
|
|
64
|
+
|
|
65
|
+
**Do**
|
|
66
|
+
|
|
67
|
+
<p>
|
|
68
|
+
Do use toasts for notifications that don't need to interrupt the user's workflow.
|
|
69
|
+
</p>
|
|
70
|
+
|
|
71
|
+
**Don't**
|
|
72
|
+
|
|
73
|
+
<p>
|
|
74
|
+
Don't use toasts for destructive, high-impact decisions that require the user's full attention.
|
|
75
|
+
</p>
|
|
76
|
+
|
|
77
|
+
## Accessibility
|
|
78
|
+
|
|
79
|
+
### Keyboard interaction
|
|
80
|
+
|
|
81
|
+
If a toast is non-actionable it is not in the page's tab sequence.
|
|
82
|
+
|
|
83
|
+
#### Actionable toasts
|
|
84
|
+
|
|
85
|
+
When a toast has interactive elements (dismiss button, action button), the tab order is:
|
|
86
|
+
|
|
87
|
+
1. Dismiss (close) button
|
|
88
|
+
2. Action button (if present)
|
|
89
|
+
|
|
90
|
+
### Live region
|
|
91
|
+
|
|
92
|
+
The entire contents of the toast must be announced as it appears on screen. Toasts use `role="status"` for info/success and `role="alert"` for warning/error, with `aria-live` set to `polite` or `assertive` accordingly.
|
|
93
|
+
|
|
94
|
+
### Reading order
|
|
95
|
+
|
|
96
|
+
In order to give all users adequate time to find and reach the action button, the toast element must be placed immediately after the user's current element.
|
|
97
|
+
|
|
98
|
+
### Time sensitive
|
|
99
|
+
|
|
100
|
+
Toasts must remain on screen long enough for users to read the message and access any action buttons. The default duration is 6 seconds; the timer pauses if focus is brought into the toast.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Core/Toast - Usage
|
|
2
|
+
|
|
3
|
+
Renders a toast inline for documentation/preview. Not for use in production.
|
|
4
|
+
|
|
5
|
+
| Prop | Type | Required | Default | Description |
|
|
6
|
+
| --- | --- | --- | --- | --- |
|
|
7
|
+
| `type` | `(typeof toastTypes)[number]` | Yes | `--` | `--` |
|
|
8
|
+
| `content` | `React.ReactNode` | Yes | `--` | `--` |
|
|
9
|
+
| `closable` | `boolean` | No | true | `--` |
|
|
10
|
+
| `action` | `ToastOptions['action']` | No | `--` | `--` |
|
|
11
|
+
| `actionSecondary` | `ToastOptions['actionSecondary']` | No | `--` | `--` |
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Core/Tooltip - Design
|
|
2
|
+
|
|
3
|
+
A component to display additional information when hovering or focusing on an interactive element.
|
|
4
|
+
|
|
5
|
+
## Properties
|
|
6
|
+
|
|
7
|
+
### Title
|
|
8
|
+
|
|
9
|
+
The text shown in the tooltip.
|
|
10
|
+
|
|
11
|
+
### Shortcut
|
|
12
|
+
|
|
13
|
+
The keyboard shortcut shown in the tooltip.
|
|
14
|
+
|
|
15
|
+
## Behavior
|
|
16
|
+
|
|
17
|
+
### Presentation
|
|
18
|
+
|
|
19
|
+
Tooltips appear after a 500ms delay when hovering a trigger element. Focusing a trigger element will show the
|
|
20
|
+
tooltip immediately.
|
|
21
|
+
|
|
22
|
+
### Dismissing
|
|
23
|
+
|
|
24
|
+
Tooltips disappear 500ms after the trigger element loses hover, immediately if focus is lost, or when another
|
|
25
|
+
element receives hover or focus that reveals a tooltip.
|
|
26
|
+
|
|
27
|
+
### Overflow
|
|
28
|
+
|
|
29
|
+
Tooltip titles should avoid wrapping where possible. When required, the title wraps to a new line when extending
|
|
30
|
+
beyond the width of the container.
|
|
31
|
+
|
|
32
|
+
### Placement
|
|
33
|
+
|
|
34
|
+
By default, tooltips appear below the trigger element. The tooltip will shift position if its placement places it
|
|
35
|
+
outside the viewport.
|
|
36
|
+
|
|
37
|
+
## Best Practices
|
|
38
|
+
|
|
39
|
+
**Do**
|
|
40
|
+
|
|
41
|
+
<p>
|
|
42
|
+
Do show only a single tooltip at a time.
|
|
43
|
+
</p>
|
|
44
|
+
|
|
45
|
+
**Don't**
|
|
46
|
+
|
|
47
|
+
<img style={{ width: '256px', marginInline: 'auto', display: 'block' }} src="tooltip-bestpractices-multiple-dont.png" />
|
|
48
|
+
|
|
49
|
+
<p>
|
|
50
|
+
Don't override tooltip behavior to show multiple at once.
|
|
51
|
+
</p>
|
|
52
|
+
|
|
53
|
+
## Accessibility
|
|
54
|
+
|
|
55
|
+
### Interaction
|
|
56
|
+
|
|
57
|
+
Tooltips are triggered on hover or focus, never on click. Tooltips do not contain interactive content.
|
|
58
|
+
|
|
59
|
+
### Custom Trigger
|
|
60
|
+
|
|
61
|
+
See the Usage page for more information on custom triggers.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Core/Tooltip - Usage
|
|
2
|
+
|
|
3
|
+
A component to display additional information when hovering or focusing on an interactive element.
|
|
4
|
+
|
|
5
|
+
## Custom Triggers
|
|
6
|
+
|
|
7
|
+
:::warning
|
|
8
|
+
|
|
9
|
+
**Custom triggers are an advanced feature and should be used with caution.** Tooltips should wrap interactive
|
|
10
|
+
elements. The defaults provided in Capra ensure an accessible experience. When using custom triggers, the dev assumes
|
|
11
|
+
responsibility for ensuring the tooltip trigger is accessible.
|
|
12
|
+
|
|
13
|
+
:::
|
|
14
|
+
|
|
15
|
+
By default, tooltips are triggered on for the `Button`, `IconButton`, `Link`, or `ButtonLink` components. For other elements, you can wrap them in a `CustomTooltipTrigger` to allow hover and focus to open the tooltip. The trigger still needs an appropriate ARIA role or semantic HTML element, and custom components should forward refs via `forwardRef` as well as spread props onto the underlying DOM node.
|
|
16
|
+
|
|
17
|
+
```tsx
|
|
18
|
+
import { Tooltip, CustomTooltipTrigger } from '@capra/core';
|
|
19
|
+
|
|
20
|
+
function MyComponent() {
|
|
21
|
+
retur(
|
|
22
|
+
<Tooltip title="Tooltip content">
|
|
23
|
+
<CustomTooltipTrigger>
|
|
24
|
+
<span role="button" tabIndex={0} style={{ cursor: 'default', textDecoration: 'underline' }}>
|
|
25
|
+
Custom trigger (span)
|
|
26
|
+
</span>
|
|
27
|
+
</CustomTooltipTrigger>
|
|
28
|
+
</Tooltip>,
|
|
29
|
+
);
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
**Important Notes**
|
|
34
|
+
|
|
35
|
+
* The trigger element must have an appropriate ARIA role or semantic HTML element.
|
|
36
|
+
* `CustomTooltipTrigger` only accepts a single child.
|
|
37
|
+
|
|
38
|
+
## Props
|
|
39
|
+
|
|
40
|
+
| Prop | Type | Required | Default | Description |
|
|
41
|
+
| --- | --- | --- | --- | --- |
|
|
42
|
+
| `children` | `React.ReactNode` | Yes | `--` | The visible trigger element. This can be a single element or a component tree, but there MUST be a focusable element (`Button`, `IconButton`, `Link`, or a custom trigger via `CustomTooltipTrigger`) in the tree. Nothing else will trigger the tooltip. |
|
|
43
|
+
| `title` | `string` | Yes | `--` | The content of the tooltip. |
|
|
44
|
+
| `shortcut` | `string` | No | `--` | Optional keyboard shortcut label shown next to the title (e.g. `⌘K`, `Ctrl+S`). |
|
|
45
|
+
| `placement` | `(typeof placements)[number]` | No | 'bottom' | The position of the tooltip relative to the trigger element.<br>@default 'bottom' |
|
|
46
|
+
| `isDisabled` | `boolean` | No | false | Whether the tooltip is disabled.<br>@default false |
|
|
47
|
+
| `getContainer` | `() => HTMLElement \| null` | No | `--` | The container to mount the tooltip in.<br>@default document.body<br><br>**Warning**: This is an unsafe feature and may cause accessibility, keyboard navigation, and other issues. Only use if you know what you are doing. |
|
|
48
|
+
| `FORCE__className` | `string` | No | `--` | 🚨 This prop is meant to be an escape hatch. 🚨<br><br>If the desired style cannot be achieved using component props, use this as a last resort. The inner workings of Capra components are implementation details and this escape hatch gives one access to those implementation details. We cannot make any guarantees that styles will applied correctly across version updates. Please use it responsibly.<br><br>Add a CSS class to the component. |
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# Core/TopNav - Design
|
|
2
|
+
|
|
3
|
+
## Properties
|
|
4
|
+
|
|
5
|
+
### Logo
|
|
6
|
+
|
|
7
|
+
The logo is required for all top navigation bars. It should link to the home page or main dashboard of the application.
|
|
8
|
+
|
|
9
|
+
### Navigation items
|
|
10
|
+
|
|
11
|
+
Navigation items represent the main sections of the application. They should be concise and clearly labeled. Use `TopNav.Item` for each navigation link.
|
|
12
|
+
|
|
13
|
+
### Actions
|
|
14
|
+
|
|
15
|
+
Actions are optional elements placed on the right side of the navigation bar. Common actions include search, notifications, user profile, and settings. Use `TopNav.Actions` to group these elements.
|
|
16
|
+
|
|
17
|
+
## Best Practices
|
|
18
|
+
|
|
19
|
+
### Navigation clarity
|
|
20
|
+
|
|
21
|
+
**Do**
|
|
22
|
+
|
|
23
|
+
<img className="w-full" src="images/guidelines/topnav/bestpractices-clarity-do.png" alt="Clear navigation labels" />
|
|
24
|
+
|
|
25
|
+
<p>
|
|
26
|
+
Do use clear, descriptive labels for navigation items.
|
|
27
|
+
</p>
|
|
28
|
+
|
|
29
|
+
**Don't**
|
|
30
|
+
|
|
31
|
+
<img className="w-full" src="images/guidelines/topnav/bestpractices-clarity-dont.png" alt="Unclear navigation labels" />
|
|
32
|
+
|
|
33
|
+
<p>
|
|
34
|
+
Don't use vague or ambiguous labels that don't clearly indicate the destination.
|
|
35
|
+
</p>
|
|
36
|
+
|
|
37
|
+
### Action overload
|
|
38
|
+
|
|
39
|
+
**Do**
|
|
40
|
+
|
|
41
|
+
<img className="w-full" src="images/guidelines/topnav/bestpractices-actions-do.png" alt="Reasonable number of actions" />
|
|
42
|
+
|
|
43
|
+
<p>
|
|
44
|
+
Do limit the number of actions to the most essential ones.
|
|
45
|
+
</p>
|
|
46
|
+
|
|
47
|
+
**Don't**
|
|
48
|
+
|
|
49
|
+
<img className="w-full" src="images/guidelines/topnav/bestpractices-actions-dont.png" alt="Too many actions" />
|
|
50
|
+
|
|
51
|
+
<p>
|
|
52
|
+
Don't overcrowd the actions area with too many buttons or icons.
|
|
53
|
+
</p>
|
|
54
|
+
|
|
55
|
+
## Accessibility
|
|
56
|
+
|
|
57
|
+
### Landmark
|
|
58
|
+
|
|
59
|
+
The top navigation uses `role="banner"` to identify it as the site-wide header landmark. This helps screen reader users quickly navigate to the main application header.
|
|
60
|
+
|
|
61
|
+
### Banner
|
|
62
|
+
|
|
63
|
+
The `TopNav` component is wrapped in a `<header>` element with `role="banner"`, which is the appropriate semantic HTML for site-wide navigation headers.
|
|
64
|
+
|
|
65
|
+
### Keyboard interaction
|
|
66
|
+
|
|
67
|
+
| Key | Function |
|
|
68
|
+
| ----------------- | -------------------------------------------------------------------------------- |
|
|
69
|
+
| `Tab` | Moves focus through interactive elements in the navigation bar in logical order. |
|
|
70
|
+
| `Enter` / `Space` | Activates focused links or buttons. |
|
|
71
|
+
| `Escape` | Closes any open dropdowns or menus within the navigation. |
|
|
72
|
+
|
|
73
|
+
### Targets
|
|
74
|
+
|
|
75
|
+
All interactive elements in the top navigation meet the minimum 24×24 CSS pixel target size requirement for WCAG 2.2 Level AA compliance.
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
# Core/TopNav - Usage
|
|
2
|
+
|
|
3
|
+
| Prop | Type | Required | Default | Description |
|
|
4
|
+
| --- | --- | --- | --- | --- |
|
|
5
|
+
| `FORCE__className` | `string` | No | `--` | 🚨 This prop is meant to be an escape hatch. 🚨<br><br>If the desired style cannot be achieved using component props, use this as a last resort. The inner workings of Capra components are implementation details and this escape hatch gives one access to those implementation details. We cannot make any guarantees that styles will applied correctly across version updates. Please use it responsibly.<br><br>Add a CSS class to the component. |
|
|
6
|
+
| `children` | `React.ReactNode` | No | `--` | `--` |
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Core/VerticalNavigation - Design
|
|
2
|
+
|
|
3
|
+
Vertical navigation shell with controlled and uncontrolled collapse support. Provides shared context for items, collapse toggle, and footer sections.
|
|
4
|
+
|
|
5
|
+
## Properties
|
|
6
|
+
|
|
7
|
+
### Layout
|
|
8
|
+
|
|
9
|
+
VerticalNavigation consists of a list of items and an optional footer. It is typically placed on the left side of the screen.
|
|
10
|
+
It supports a collapsed state to save space.
|
|
11
|
+
|
|
12
|
+
### Items
|
|
13
|
+
|
|
14
|
+
Navigation items can have icons and labels. Sub-items are indented and do not have icons.
|
|
15
|
+
Items can be links (using `href`) or buttons (using `onClick`).
|
|
16
|
+
|
|
17
|
+
## Accessibility
|
|
18
|
+
|
|
19
|
+
### Keyboard interaction
|
|
20
|
+
|
|
21
|
+
| Key | Function |
|
|
22
|
+
| ------------------- | ---------------------------------------------------------------------------- |
|
|
23
|
+
| `Tab` / `Shift-Tab` | Moves focus through the interactive items (links, buttons, collapse toggle). |
|
|
24
|
+
| `Enter` / `Space` | Activates the focused item (follows link or triggers action). |
|
|
25
|
+
|
|
26
|
+
### WAI-ARIA Roles, States, and Properties
|
|
27
|
+
|
|
28
|
+
* The navigation container has `role="navigation"` (implicit for `<nav>`).
|
|
29
|
+
* The `aria-label` provides a descriptive name for the navigation region (default: "Cribl product navigation").
|
|
30
|
+
* The collapse toggle has `aria-expanded` reflecting the collapsed state.
|
|
31
|
+
* Active items use `aria-current="page"` to indicate the current page.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Core/VerticalNavigation - Usage
|
|
2
|
+
|
|
3
|
+
Vertical navigation shell with controlled and uncontrolled collapse support. Provides shared context for items, collapse toggle, and footer sections.
|
|
4
|
+
|
|
5
|
+
### VerticalNavigation
|
|
6
|
+
|
|
7
|
+
| Prop | Type | Required | Default | Description |
|
|
8
|
+
| --- | --- | --- | --- | --- |
|
|
9
|
+
| `FORCE__className` | `string` | No | `--` | 🚨 This prop is meant to be an escape hatch. 🚨<br><br>If the desired style cannot be achieved using component props, use this as a last resort. The inner workings of Capra components are implementation details and this escape hatch gives one access to those implementation details. We cannot make any guarantees that styles will applied correctly across version updates. Please use it responsibly.<br><br>Add a CSS class to the component. |
|
|
10
|
+
| `collapsed` | `boolean` | No | `--` | Controlled collapsed state. |
|
|
11
|
+
| `onCollapseChange` | `(collapsed: boolean) => void` | No | `--` | Callback fired when the collapsed state changes. |
|
|
12
|
+
| `defaultCollapsed` | `boolean` | No | false | Default collapsed state for uncontrolled mode.<br>@default false |
|
|
13
|
+
| `aria-label` | `string` | No | 'Cribl product navigation' | `--` |
|
|
14
|
+
|
|
15
|
+
### Examples
|
|
16
|
+
|
|
17
|
+
Various product navigation configurations.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Core/VisuallyHidden - Design
|
|
2
|
+
|
|
3
|
+
VisuallyHidden is a component that hides its children from the visual rendering, but still makes them available to screen readers.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
VisuallyHidden is a utility component that removes content from the visual flow while keeping it accessible to assistive technologies such as screen readers. It uses a well-established CSS technique that clips the element to a 1×1 pixel area without using `display: none` or `visibility: hidden`, which would remove it from the accessibility tree entirely.
|
|
8
|
+
|
|
9
|
+
Use VisuallyHidden when you need to provide context or labels for screen reader users that would be redundant or unnecessary in the visual design.
|
|
10
|
+
|
|
11
|
+
## Use Cases
|
|
12
|
+
|
|
13
|
+
### Hidden labels for icon-only controls
|
|
14
|
+
|
|
15
|
+
Icon-only buttons and controls must have accessible names. Wrap a text label in VisuallyHidden to provide one without affecting the visual design.
|
|
16
|
+
|
|
17
|
+
### Supplementary link text
|
|
18
|
+
|
|
19
|
+
Links like "Read more" lack context when read in isolation. Use VisuallyHidden to append descriptive text that screen readers announce.
|
|
20
|
+
|
|
21
|
+
### Form labels
|
|
22
|
+
|
|
23
|
+
When a form input has a visible placeholder but no visible label, use VisuallyHidden to associate a proper `<label>` element with the input.
|
|
24
|
+
|
|
25
|
+
### Skip links
|
|
26
|
+
|
|
27
|
+
Skip navigation links allow keyboard users to bypass repeated content. The link text can be visually hidden until it receives focus.
|
|
28
|
+
|
|
29
|
+
## Best Practices
|
|
30
|
+
|
|
31
|
+
**Do**
|
|
32
|
+
|
|
33
|
+
<p>
|
|
34
|
+
Do use VisuallyHidden to provide accessible names for icon-only buttons and controls.
|
|
35
|
+
</p>
|
|
36
|
+
|
|
37
|
+
**Don't**
|
|
38
|
+
|
|
39
|
+
<p>
|
|
40
|
+
Don't use VisuallyHidden to hide content that all users should see. If the content is meaningful, it should be visible.
|
|
41
|
+
</p>
|
|
42
|
+
|
|
43
|
+
**Do**
|
|
44
|
+
|
|
45
|
+
<p>
|
|
46
|
+
Do use VisuallyHidden to add context to ambiguous links like "Read more" or "Learn more".
|
|
47
|
+
</p>
|
|
48
|
+
|
|
49
|
+
**Don't**
|
|
50
|
+
|
|
51
|
+
<p>
|
|
52
|
+
Don't use
|
|
53
|
+
|
|
54
|
+
`display: none`
|
|
55
|
+
|
|
56
|
+
or
|
|
57
|
+
|
|
58
|
+
`visibility: hidden`
|
|
59
|
+
|
|
60
|
+
when content should remain available to assistive technologies.
|
|
61
|
+
</p>
|
|
62
|
+
|
|
63
|
+
## Accessibility
|
|
64
|
+
|
|
65
|
+
### Purpose
|
|
66
|
+
|
|
67
|
+
VisuallyHidden exists specifically to improve accessibility. It bridges the gap between visual design and the information needs of assistive technology users.
|
|
68
|
+
|
|
69
|
+
### When to Use
|
|
70
|
+
|
|
71
|
+
### WCAG 1.1.1 — Non-text Content (Level A)
|
|
72
|
+
|
|
73
|
+
Provide text alternatives for non-text content such as icon-only buttons. VisuallyHidden allows you to add an accessible name without altering the visual design.
|
|
74
|
+
|
|
75
|
+
### WCAG 2.4.4 — Link Purpose (Level A)
|
|
76
|
+
|
|
77
|
+
Links should make sense out of context. When visual context makes the purpose clear but the link text alone is ambiguous (e.g., "Read more"), use VisuallyHidden to add clarifying text.
|
|
78
|
+
|
|
79
|
+
### WCAG 2.4.6 — Headings and Labels (Level AA)
|
|
80
|
+
|
|
81
|
+
Form inputs should have descriptive labels. When a visible label would be redundant with other visual cues, VisuallyHidden can provide a programmatic label for assistive technologies.
|
|
82
|
+
|
|
83
|
+
### Important Notes
|
|
84
|
+
|
|
85
|
+
* VisuallyHidden content **is not** hidden from screen readers — that is its entire purpose.
|
|
86
|
+
* Do **not** use `aria-hidden="true"` on VisuallyHidden or its children, as this would negate its purpose.
|
|
87
|
+
* Prefer `aria-label` or `aria-labelledby` when labeling a single element. Use VisuallyHidden when you need to provide more complex or multi-element content to assistive technologies.
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# Core/VisuallyHidden - Usage
|
|
2
|
+
|
|
3
|
+
VisuallyHidden is a component that hides its children from the visual rendering, but still makes them available to screen readers.
|
|
4
|
+
|
|
5
|
+
| Prop | Type | Required | Default | Description |
|
|
6
|
+
| --- | --- | --- | --- | --- |
|
|
7
|
+
| `children` | `React.ReactNode` | Yes | `--` | `--` |
|
|
8
|
+
|
|
9
|
+
## Usage
|
|
10
|
+
|
|
11
|
+
```tsx
|
|
12
|
+
import { VisuallyHidden } from '@cribl/capra-core';
|
|
13
|
+
|
|
14
|
+
// Accessible label for an icon-only button
|
|
15
|
+
<button>
|
|
16
|
+
🔔 <VisuallyHidden>Notifications</VisuallyHidden>
|
|
17
|
+
</button>
|
|
18
|
+
|
|
19
|
+
// Descriptive link text
|
|
20
|
+
<a href="/docs">
|
|
21
|
+
Read more<VisuallyHidden> about our API documentation</VisuallyHidden>
|
|
22
|
+
</a>
|
|
23
|
+
|
|
24
|
+
// Hidden form label
|
|
25
|
+
<VisuallyHidden>
|
|
26
|
+
<label htmlFor="search">Search</label>
|
|
27
|
+
</VisuallyHidden>
|
|
28
|
+
<input id="search" type="search" placeholder="Search..." />
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## How It Works
|
|
32
|
+
|
|
33
|
+
The component renders a `<span>` element with CSS that clips it to a 1×1 pixel area using `clip-path: inset(100%)`. This keeps the content in the DOM and accessibility tree while removing it from the visual layout.
|
|
34
|
+
|
|
35
|
+
The `:not(:focus):not(:active)` selector ensures that if a focusable element (like a skip link) is nested inside, it becomes visible when focused.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# History/Changelogs/@capra-core
|
|
2
|
+
|
|
3
|
+
### 1.7.0
|
|
4
|
+
|
|
5
|
+
#### Minor Changes
|
|
6
|
+
|
|
7
|
+
* [540b651](https://bitbucket.org/cribl/capra-ui/commits/540b651): Add `onPress` event handler to `Menu.Item` and deprecate `onClick`
|
|
8
|
+
|
|
9
|
+
#### Patch Changes
|
|
10
|
+
|
|
11
|
+
* [540b651](https://bitbucket.org/cribl/capra-ui/commits/540b651): Fix issue where event in `Menu.Item` `onClick` was not bubbling correctly
|
|
12
|
+
* [684cc26](https://bitbucket.org/cribl/capra-ui/commits/684cc26): Remove invalid `aria-orientation` attribute in TabNav component.
|
|
13
|
+
|
|
14
|
+
### 1.6.0
|
|
15
|
+
|
|
16
|
+
#### Minor Changes
|
|
17
|
+
|
|
18
|
+
* [e99f46d](https://bitbucket.org/cribl/capra-ui/commits/e99f46d): Include LLM-friendly docs in published packages
|
|
19
|
+
|
|
20
|
+
#### Patch Changes
|
|
21
|
+
|
|
22
|
+
* [ce30088](https://bitbucket.org/cribl/capra-ui/commits/ce30088): Increase `Modal` z-index so it layers correctly
|
|
23
|
+
* [8a1bbe5](https://bitbucket.org/cribl/capra-ui/commits/8a1bbe5): Update `TextInput` internal spacing so Chrome's autofill backgrounds look better
|
|
24
|
+
* Updated dependencies [e99f46d](https://bitbucket.org/cribl/capra-ui/commits/e99f46d) — Include LLM-friendly docs in published packages
|
|
25
|
+
* @capra/icons\@1.7.0
|
|
26
|
+
|
|
27
|
+
### 1.5.3
|
|
28
|
+
|
|
29
|
+
#### Patch Changes
|
|
30
|
+
|
|
31
|
+
* [5387e9d](https://bitbucket.org/cribl/capra-ui/commits/5387e9d): Fix an issue where `EmptyState` crashed in Webpack bundles
|
|
32
|
+
|
|
33
|
+
### 1.5.2
|
|
34
|
+
|
|
35
|
+
#### Patch Changes
|
|
36
|
+
|
|
37
|
+
* [961667d](https://bitbucket.org/cribl/capra-ui/commits/961667d): Update the `icon` prop for `Tag` to accept logos from `@capra/icons/logos`.
|
|
38
|
+
* [1128996](https://bitbucket.org/cribl/capra-ui/commits/1128996): Add documentation links to README and `package.json`
|
|
39
|
+
* Updated dependencies [1128996](https://bitbucket.org/cribl/capra-ui/commits/1128996) — Add documentation links to README and `package.json`
|
|
40
|
+
* @capra/icons\@1.6.1
|
|
41
|
+
|
|
42
|
+
### 1.5.1
|
|
43
|
+
|
|
44
|
+
#### Patch Changes
|
|
45
|
+
|
|
46
|
+
* [7fdf2f5](https://bitbucket.org/cribl/capra-ui/commits/7fdf2f5): Fix `TabNav` horizontal submenu visibility so click, hover, keyboard toggles, `Escape`, and focus containment behave consistently. Remove margin.
|
|
47
|
+
* [363909c](https://bitbucket.org/cribl/capra-ui/commits/363909c): Import `EmptyState` illustrations directly to help with tree-shaking and load times
|
|
48
|
+
* [0219174](https://bitbucket.org/cribl/capra-ui/commits/0219174): Drawer no longer closes on browser Back, and left-placed drawers now use the same close easing behavior as right-placed drawers.
|
|
49
|
+
* [186bcfe](https://bitbucket.org/cribl/capra-ui/commits/186bcfe): Reduce `Tooltip` hover delay to 500ms
|
|
50
|
+
|
|
51
|
+
### 1.5.0
|
|
52
|
+
|
|
53
|
+
#### Minor Changes
|
|
54
|
+
|
|
55
|
+
* [30b2a43](https://bitbucket.org/cribl/capra-ui/commits/30b2a43): Prepare packages for publishing to NPM
|
|
56
|
+
|
|
57
|
+
#### Patch Changes
|
|
58
|
+
|
|
59
|
+
* Updated dependencies [30b2a43](https://bitbucket.org/cribl/capra-ui/commits/30b2a43) — Prepare packages for publishing to NPM
|
|
60
|
+
* @capra/icons\@1.6.0
|
package/docs/index.md
ADDED
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# @capra/core
|
|
2
|
+
|
|
3
|
+
This file contains links to the documentation for the `@capra/core` package. This is a local mirror of the documentation located at https://capra.cribl.io/llms.txt.
|
|
4
|
+
|
|
5
|
+
Embedded documentation is available on the filesystem for each of these packages:
|
|
6
|
+
|
|
7
|
+
- `@capra/core`
|
|
8
|
+
- `@capra/domain`
|
|
9
|
+
- `@capra/icons`
|
|
10
|
+
- `@capra/theme`
|
|
11
|
+
|
|
12
|
+
## Documentation
|
|
13
|
+
|
|
14
|
+
- [Conventions](./conventions--docs.md)
|
|
15
|
+
- [Using Capra](./using-capra--docs.md)
|
|
16
|
+
- [Core/Alert - Design](./core-alert--design.md)
|
|
17
|
+
- [Core/Alert - Usage](./core-alert--usage.md)
|
|
18
|
+
- [Core/Anchor - Design](./core-anchor--design.md)
|
|
19
|
+
- [Core/Anchor - Usage](./core-anchor--usage.md)
|
|
20
|
+
- [Core/AutocompleteField - Design](./core-autocompletefield--design.md)
|
|
21
|
+
- [Core/AutocompleteField - Usage](./core-autocompletefield--usage.md)
|
|
22
|
+
- [Core/Badge - Design](./core-badge--design.md)
|
|
23
|
+
- [Core/Badge - Usage](./core-badge--usage.md)
|
|
24
|
+
- [Core/Breadcrumbs - Design](./core-breadcrumbs--design.md)
|
|
25
|
+
- [Core/Breadcrumbs - Usage](./core-breadcrumbs--usage.md)
|
|
26
|
+
- [Core/Button - Design](./core-button--design.md)
|
|
27
|
+
- [Core/Button - Usage](./core-button--usage.md)
|
|
28
|
+
- [Core/ButtonLink - Design](./core-buttonlink--design.md)
|
|
29
|
+
- [Core/ButtonLink - Usage](./core-buttonlink--usage.md)
|
|
30
|
+
- [Core/Card - Design](./core-card--design.md)
|
|
31
|
+
- [Core/Card - Usage](./core-card--usage.md)
|
|
32
|
+
- [Core/Checkbox - Design](./core-checkbox--design.md)
|
|
33
|
+
- [Core/Checkbox - Usage](./core-checkbox--usage.md)
|
|
34
|
+
- [Core/Collapse - Design](./core-collapse--design.md)
|
|
35
|
+
- [Core/Collapse - Usage](./core-collapse--usage.md)
|
|
36
|
+
- [Core/DatePickerField - Design](./core-datepickerfield--design.md)
|
|
37
|
+
- [Core/DatePickerField - Usage](./core-datepickerfield--usage.md)
|
|
38
|
+
- [Core/DateRangePickerField - Design](./core-daterangepickerfield--design.md)
|
|
39
|
+
- [Core/DateRangePickerField - Usage](./core-daterangepickerfield--usage.md)
|
|
40
|
+
- [Core/Divider - Design](./core-divider--design.md)
|
|
41
|
+
- [Core/Divider - Usage](./core-divider--usage.md)
|
|
42
|
+
- [Core/Drawer - Design](./core-drawer--design.md)
|
|
43
|
+
- [Core/Drawer - Usage](./core-drawer--usage.md)
|
|
44
|
+
- [Core/EmptyState - Design](./core-emptystate--design.md)
|
|
45
|
+
- [Core/EmptyState - Usage](./core-emptystate--usage.md)
|
|
46
|
+
- [Core/HelperText - Design](./core-helpertext--design.md)
|
|
47
|
+
- [Core/HelperText - Usage](./core-helpertext--usage.md)
|
|
48
|
+
- [Core/IconButton - Design](./core-iconbutton--design.md)
|
|
49
|
+
- [Core/IconButton - Usage](./core-iconbutton--usage.md)
|
|
50
|
+
- [Core/InputRow - Design](./core-inputrow--design.md)
|
|
51
|
+
- [Core/InputRow - Usage](./core-inputrow--usage.md)
|
|
52
|
+
- [Core/Label - Design](./core-label--design.md)
|
|
53
|
+
- [Core/Label - Usage](./core-label--usage.md)
|
|
54
|
+
- [Core/Link - Design](./core-link--design.md)
|
|
55
|
+
- [Core/Link - Usage](./core-link--usage.md)
|
|
56
|
+
- [Core/ListItem - Design](./core-listitem--design.md)
|
|
57
|
+
- [Core/ListItem - Usage](./core-listitem--usage.md)
|
|
58
|
+
- [Core/Menu - Design](./core-menu--design.md)
|
|
59
|
+
- [Core/Menu - Usage](./core-menu--usage.md)
|
|
60
|
+
- [Core/Modal - Design](./core-modal--design.md)
|
|
61
|
+
- [Core/Modal - Usage](./core-modal--usage.md)
|
|
62
|
+
- [Core/NumberField - Design](./core-numberfield--design.md)
|
|
63
|
+
- [Core/NumberField - Usage](./core-numberfield--usage.md)
|
|
64
|
+
- [Core/Pagination - Design](./core-pagination--design.md)
|
|
65
|
+
- [Core/Pagination - Usage](./core-pagination--usage.md)
|
|
66
|
+
- [Core/PasswordField - Design](./core-passwordfield--design.md)
|
|
67
|
+
- [Core/PasswordField - Usage](./core-passwordfield--usage.md)
|
|
68
|
+
- [Core/Pill - Design](./core-pill--design.md)
|
|
69
|
+
- [Core/Pill - Usage](./core-pill--usage.md)
|
|
70
|
+
- [Core/Popover - Design](./core-popover--design.md)
|
|
71
|
+
- [Core/Popover - Usage](./core-popover--usage.md)
|
|
72
|
+
- [Core/Radio - Design](./core-radio--design.md)
|
|
73
|
+
- [Core/Radio - Usage](./core-radio--usage.md)
|
|
74
|
+
- [Core/RadioGroup - Design](./core-radiogroup--design.md)
|
|
75
|
+
- [Core/RadioGroup - Usage](./core-radiogroup--usage.md)
|
|
76
|
+
- [Core/RadioTile - Design](./core-radiotile--design.md)
|
|
77
|
+
- [Core/RadioTile - Usage](./core-radiotile--usage.md)
|
|
78
|
+
- [Core/Ribbon - Design](./core-ribbon--design.md)
|
|
79
|
+
- [Core/Ribbon - Usage](./core-ribbon--usage.md)
|
|
80
|
+
- [Core/Skeleton - Design](./core-skeleton--design.md)
|
|
81
|
+
- [Core/Skeleton - Usage](./core-skeleton--usage.md)
|
|
82
|
+
- [Core/SkeletonGroup - Design](./core-skeletongroup--design.md)
|
|
83
|
+
- [Core/SkeletonGroup - Usage](./core-skeletongroup--usage.md)
|
|
84
|
+
- [Core/Spinner - Design](./core-spinner--design.md)
|
|
85
|
+
- [Core/Spinner - Usage](./core-spinner--usage.md)
|
|
86
|
+
- [Core/Switch - Design](./core-switch--design.md)
|
|
87
|
+
- [Core/Switch - Usage](./core-switch--usage.md)
|
|
88
|
+
- [Core/TabNav - Design](./core-tabnav--design.md)
|
|
89
|
+
- [Core/TabNav - Usage](./core-tabnav--usage.md)
|
|
90
|
+
- [Core/Tag - Design](./core-tag--design.md)
|
|
91
|
+
- [Core/Tag - Usage](./core-tag--usage.md)
|
|
92
|
+
- [Core/Text - Design](./core-text--design.md)
|
|
93
|
+
- [Core/Text - Usage](./core-text--usage.md)
|
|
94
|
+
- [Core/TextArea - Design](./core-textarea--design.md)
|
|
95
|
+
- [Core/TextArea - Usage](./core-textarea--usage.md)
|
|
96
|
+
- [Core/TextField - Design](./core-textfield--design.md)
|
|
97
|
+
- [Core/TextField - Usage](./core-textfield--usage.md)
|
|
98
|
+
- [Core/TextInput - Design](./core-textinput--design.md)
|
|
99
|
+
- [Core/TextInput - Usage](./core-textinput--usage.md)
|
|
100
|
+
- [Core/Toast - Design](./core-toast--design.md)
|
|
101
|
+
- [Core/Toast - Usage](./core-toast--usage.md)
|
|
102
|
+
- [Core/Tooltip - Design](./core-tooltip--design.md)
|
|
103
|
+
- [Core/Tooltip - Usage](./core-tooltip--usage.md)
|
|
104
|
+
- [Core/TopNav - Design](./core-topnav--design.md)
|
|
105
|
+
- [Core/TopNav - Usage](./core-topnav--usage.md)
|
|
106
|
+
- [Core/VerticalNavigation - Design](./core-verticalnavigation--design.md)
|
|
107
|
+
- [Core/VerticalNavigation - Usage](./core-verticalnavigation--usage.md)
|
|
108
|
+
- [Core/VisuallyHidden - Design](./core-visuallyhidden--design.md)
|
|
109
|
+
- [Core/VisuallyHidden - Usage](./core-visuallyhidden--usage.md)
|
|
110
|
+
- [History/Changelogs/@capra-core](./history-changelogs-capra-core--docs.md)
|