@xsolla/xui-breadcrumbs 0.150.0 → 0.151.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.
Files changed (2) hide show
  1. package/README.md +66 -107
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,24 +1,27 @@
1
1
  # Breadcrumbs
2
2
 
3
- A cross-platform React breadcrumbs navigation component that displays the current page location within a hierarchical structure. Supports custom separators and click handlers.
3
+ A breadcrumb trail showing a page's location within a hierarchy. Renders a `<nav aria-label="Breadcrumb">` with an ordered list, a default chevron separator, and three size variants.
4
4
 
5
5
  ## Installation
6
6
 
7
7
  ```bash
8
8
  npm install @xsolla/xui-breadcrumbs
9
- # or
10
- yarn add @xsolla/xui-breadcrumbs
11
9
  ```
12
10
 
13
- ## Demo
11
+ ## Imports
14
12
 
15
- ### Basic Breadcrumbs
13
+ ```tsx
14
+ import { Breadcrumbs } from '@xsolla/xui-breadcrumbs';
15
+ import type { BreadcrumbItem } from '@xsolla/xui-breadcrumbs';
16
+ ```
17
+
18
+ ## Quick start
16
19
 
17
20
  ```tsx
18
21
  import * as React from 'react';
19
22
  import { Breadcrumbs } from '@xsolla/xui-breadcrumbs';
20
23
 
21
- export default function BasicBreadcrumbs() {
24
+ export default function Example() {
22
25
  return (
23
26
  <Breadcrumbs
24
27
  items={[
@@ -32,83 +35,49 @@ export default function BasicBreadcrumbs() {
32
35
  }
33
36
  ```
34
37
 
35
- ### With Click Handlers
36
-
37
- ```tsx
38
- import * as React from 'react';
39
- import { Breadcrumbs } from '@xsolla/xui-breadcrumbs';
38
+ ## API Reference
40
39
 
41
- export default function ClickableBreadcrumbs() {
42
- const handleNavigate = (path: string) => {
43
- console.log('Navigate to:', path);
44
- };
40
+ ### `<Breadcrumbs>`
45
41
 
46
- return (
47
- <Breadcrumbs
48
- items={[
49
- { label: 'Home', onClick: () => handleNavigate('/') },
50
- { label: 'Settings', onClick: () => handleNavigate('/settings') },
51
- { label: 'Profile' },
52
- ]}
53
- />
54
- );
55
- }
56
- ```
42
+ | Prop | Type | Default | Description |
43
+ | --- | --- | --- | --- |
44
+ | `items` | `BreadcrumbItem[]` | - | Trail items, ordered root-to-current. Required. |
45
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Font / icon size preset (12/14/16px text). |
46
+ | `stretched` | `boolean` | `false` | Centre the trail and stretch the container to full width. |
47
+ | `separator` | `ReactNode` | chevron icon | Custom separator placed between items (rendered `aria-hidden`). |
48
+ | `backgroundColor` | `string` | - | Container background colour. |
49
+ | `testID` | `string` | - | Test identifier. |
57
50
 
58
- ### Stretched Layout
51
+ Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
59
52
 
60
- ```tsx
61
- import * as React from 'react';
62
- import { Breadcrumbs } from '@xsolla/xui-breadcrumbs';
63
-
64
- export default function StretchedBreadcrumbs() {
65
- return (
66
- <div style={{ width: '100%' }}>
67
- <Breadcrumbs
68
- stretched={true}
69
- items={[
70
- { label: 'Home', href: '/' },
71
- { label: 'Dashboard', href: '/dashboard' },
72
- { label: 'Reports' },
73
- ]}
74
- />
75
- </div>
76
- );
77
- }
78
- ```
53
+ ### `BreadcrumbItem`
79
54
 
80
- ## Anatomy
55
+ | Field | Type | Description |
56
+ | --- | --- | --- |
57
+ | `label` | `string` | Display text. Required. |
58
+ | `href` | `string` | Link target. Ignored when the item is the last in `items` (the active item never renders a hyperlink). |
59
+ | `onClick` | `() => void` | Click handler. Not invoked when the item is active or disabled. When `href` is also provided, `preventDefault()` is called before invoking — browser navigation is suppressed, so handle navigation yourself. |
60
+ | `disabled` | `boolean` | Reduces opacity, removes tab stop, and prevents interaction. |
81
61
 
82
- ```jsx
83
- import { Breadcrumbs } from '@xsolla/xui-breadcrumbs';
62
+ ### Active-item behaviour
84
63
 
85
- <Breadcrumbs
86
- items={[ // Array of breadcrumb items
87
- { label: 'Home', href: '/' },
88
- { label: 'Current' },
89
- ]}
90
- size="md" // Size variant
91
- stretched={false} // Center and stretch to full width
92
- separator={<CustomIcon />} // Custom separator element
93
- backgroundColor="transparent" // Background color
94
- />
95
- ```
64
+ The last item in `items` is treated as the current page. It renders without an `href` or click handler, gets `aria-current="page"`, and is excluded from the tab order regardless of any `href`/`onClick` you pass.
96
65
 
97
66
  ## Examples
98
67
 
99
- ### Breadcrumbs Sizes
68
+ ### Sizes
100
69
 
101
70
  ```tsx
102
71
  import * as React from 'react';
103
72
  import { Breadcrumbs } from '@xsolla/xui-breadcrumbs';
104
73
 
105
- export default function BreadcrumbsSizes() {
106
- const items = [
107
- { label: 'Home', href: '/' },
108
- { label: 'Products', href: '/products' },
109
- { label: 'Details' },
110
- ];
74
+ const items = [
75
+ { label: 'Home', href: '/' },
76
+ { label: 'Products', href: '/products' },
77
+ { label: 'Details' },
78
+ ];
111
79
 
80
+ export default function Example() {
112
81
  return (
113
82
  <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
114
83
  <Breadcrumbs size="sm" items={items} />
@@ -119,13 +88,13 @@ export default function BreadcrumbsSizes() {
119
88
  }
120
89
  ```
121
90
 
122
- ### Custom Separator
91
+ ### Custom separator
123
92
 
124
93
  ```tsx
125
94
  import * as React from 'react';
126
95
  import { Breadcrumbs } from '@xsolla/xui-breadcrumbs';
127
96
 
128
- export default function CustomSeparator() {
97
+ export default function Example() {
129
98
  return (
130
99
  <Breadcrumbs
131
100
  separator={<span style={{ margin: '0 8px' }}>/</span>}
@@ -139,62 +108,52 @@ export default function CustomSeparator() {
139
108
  }
140
109
  ```
141
110
 
142
- ### With Disabled Items
111
+ ### Click handlers (router integration)
143
112
 
144
113
  ```tsx
145
114
  import * as React from 'react';
146
115
  import { Breadcrumbs } from '@xsolla/xui-breadcrumbs';
147
116
 
148
- export default function DisabledBreadcrumbs() {
117
+ export default function Example() {
118
+ const navigate = (path: string) => {
119
+ // your router's navigate fn
120
+ };
121
+
149
122
  return (
150
123
  <Breadcrumbs
151
124
  items={[
152
- { label: 'Home', href: '/' },
153
- { label: 'Restricted', disabled: true },
154
- { label: 'Current Page' },
125
+ { label: 'Home', onClick: () => navigate('/') },
126
+ { label: 'Settings', onClick: () => navigate('/settings') },
127
+ { label: 'Profile' },
155
128
  ]}
156
129
  />
157
130
  );
158
131
  }
159
132
  ```
160
133
 
161
- ## API Reference
134
+ ### Disabled item
162
135
 
163
- ### Breadcrumbs
164
-
165
- **Breadcrumbs Props:**
136
+ ```tsx
137
+ import * as React from 'react';
138
+ import { Breadcrumbs } from '@xsolla/xui-breadcrumbs';
166
139
 
167
- | Prop | Type | Default | Description |
168
- | :--- | :--- | :------ | :---------- |
169
- | items | `BreadcrumbItem[]` | - | **Required.** Array of breadcrumb items. |
170
- | size | `"sm" \| "md" \| "lg"` | `"md"` | Size variant. |
171
- | stretched | `boolean` | `false` | Center content and stretch to full width. |
172
- | separator | `ReactNode` | Chevron icon | Custom separator element. |
173
- | backgroundColor | `string` | - | Background color. |
174
- | testID | `string` | - | Test identifier. |
175
-
176
- **BreadcrumbItem Interface:**
177
-
178
- ```typescript
179
- interface BreadcrumbItem {
180
- label: string; // Display text
181
- href?: string; // Link URL
182
- onClick?: () => void; // Click handler
183
- disabled?: boolean; // Disabled state
140
+ export default function Example() {
141
+ return (
142
+ <Breadcrumbs
143
+ items={[
144
+ { label: 'Home', href: '/' },
145
+ { label: 'Restricted', disabled: true },
146
+ { label: 'Current Page' },
147
+ ]}
148
+ />
149
+ );
184
150
  }
185
151
  ```
186
152
 
187
- ## Behavior
188
-
189
- - Last item is always displayed as active/current page
190
- - Non-last items are clickable (via href or onClick)
191
- - Disabled items show reduced opacity and aren't clickable
192
- - Separator appears between each item
193
-
194
153
  ## Accessibility
195
154
 
196
- - Uses `<nav>` element with `aria-label="Breadcrumb"`
197
- - Uses `<ol>` for semantic list structure
198
- - Current page has `aria-current="page"`
199
- - Non-active items have proper link/button roles
200
- - Separators are hidden from screen readers
155
+ - Container is `<nav aria-label="Breadcrumb">` wrapping a semantic `<ol>`.
156
+ - The active (last) item carries `aria-current="page"` and is not focusable.
157
+ - Separators are decorative (`aria-hidden`).
158
+ - Disabled items are removed from the tab order (`tabIndex={-1}`).
159
+ - Items with `href` render as `<a role="link">`; items without `href` render as `<div role="button" tabIndex={0}>` — keyboard activation depends on the host environment, prefer `href` when navigating to a real URL.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xsolla/xui-breadcrumbs",
3
- "version": "0.150.0",
3
+ "version": "0.151.0",
4
4
  "main": "./web/index.js",
5
5
  "module": "./web/index.mjs",
6
6
  "types": "./web/index.d.ts",
@@ -10,8 +10,8 @@
10
10
  "build:native": "PLATFORM=native tsup"
11
11
  },
12
12
  "dependencies": {
13
- "@xsolla/xui-core": "0.150.0",
14
- "@xsolla/xui-primitives-core": "0.150.0"
13
+ "@xsolla/xui-core": "0.151.0",
14
+ "@xsolla/xui-primitives-core": "0.151.0"
15
15
  },
16
16
  "peerDependencies": {
17
17
  "react": ">=16.8.0"