Skip to content

Commit 4820795

Browse files
ist-h-iist-h-i
authored
feat(docs): translate guide/aria/combobox to Japanese (#1176)
1 parent cd1bddf commit 4820795

2 files changed

Lines changed: 377 additions & 81 deletions

File tree

‎adev-ja/src/content/guide/aria/combobox.en.md‎

Lines changed: 296 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,296 @@
1+
<docs-decorative-header title="Combobox">
2+
</docs-decorative-header>
3+
4+
<docs-pill-row>
5+
<docs-pill href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/" title="Combobox ARIA pattern"/>
6+
<docs-pill href="/api?query=combobox#angular_aria_combobox" title="Combobox API Reference"/>
7+
</docs-pill-row>
8+
9+
## Overview
10+
11+
A directive that coordinates a trigger element (such as a text input, button, or `div`) with a popup, providing the primitive directive for autocomplete, select, and multiselect patterns.
12+
13+
<docs-tab-group>
14+
<docs-tab label="Basic">
15+
<docs-code-multifile preview hideCode path="adev/src/content/examples/aria/autocomplete/src/manual/app/app.ts">
16+
<docs-code header="app.ts" path="adev/src/content/examples/aria/autocomplete/src/manual/app/app.ts"/>
17+
<docs-code header="app.html" path="adev/src/content/examples/aria/autocomplete/src/manual/app/app.html"/>
18+
<docs-code header="app.css" path="adev/src/content/examples/aria/autocomplete/src/manual/app/app.css"/>
19+
</docs-code-multifile>
20+
</docs-tab>
21+
22+
<docs-tab label="Material">
23+
<docs-code-multifile preview hideCode path="adev/src/content/examples/aria/autocomplete/src/manual/material/app/app.ts">
24+
<docs-code header="app.ts" path="adev/src/content/examples/aria/autocomplete/src/manual/material/app/app.ts"/>
25+
<docs-code header="app.html" path="adev/src/content/examples/aria/autocomplete/src/manual/material/app/app.html"/>
26+
<docs-code header="app.css" path="adev/src/content/examples/aria/autocomplete/src/manual/material/app/app.css"/>
27+
</docs-code-multifile>
28+
</docs-tab>
29+
30+
<docs-tab label="Retro">
31+
<docs-code-multifile preview hideCode path="adev/src/content/examples/aria/autocomplete/src/manual/retro/app/app.ts">
32+
<docs-code header="app.ts" path="adev/src/content/examples/aria/autocomplete/src/manual/retro/app/app.ts"/>
33+
<docs-code header="app.html" path="adev/src/content/examples/aria/autocomplete/src/manual/retro/app/app.html"/>
34+
<docs-code header="app.css" path="adev/src/content/examples/aria/autocomplete/src/manual/retro/app/app.css"/>
35+
</docs-code-multifile>
36+
</docs-tab>
37+
</docs-tab-group>
38+
39+
## Usage
40+
41+
Combobox is the primitive directive that coordinates an interactive trigger element (such as a text input, button, or `div`) with a popup. It provides the foundation for autocomplete, select, and multiselect patterns. Consider using combobox directly when:
42+
43+
- **Building custom autocomplete patterns** - Creating specialized filtering or suggestion behavior
44+
- **Creating custom selection components** - Developing dropdowns with unique requirements
45+
- **Coordinating input with popup** - Pairing text input with listbox, tree, or dialog content
46+
- **Implementing custom filtering** - Filtering and orchestrating matching options in user space
47+
48+
Use documented patterns instead when:
49+
50+
- Standard autocomplete with filtering is needed - See the [Autocomplete pattern](guide/aria/autocomplete) for ready-to-use examples
51+
- Single-selection dropdowns are needed - See the [Select pattern](guide/aria/select) for complete dropdown implementation
52+
- Multiple-selection dropdowns are needed - See the [Multiselect pattern](guide/aria/multiselect) for multi-select with compact display
53+
54+
NOTE: The [Autocomplete](guide/aria/autocomplete), [Select](guide/aria/select), and [Multiselect](guide/aria/multiselect) guides show documented patterns that combine this directive with [Listbox](guide/aria/listbox) for specific use cases.
55+
56+
## Features
57+
58+
Angular's combobox provides a fully accessible input-popup coordination system with:
59+
60+
- **Trigger Element with Popup** - Coordinates trigger element with popup content
61+
- **Flexible Coordination** - Integrates seamlessly with standard layouts (listbox, tree, grid, or dialog)
62+
- **Keyboard Navigation** - Arrow keys, Enter, Escape handling
63+
- **Screen Reader Support** - Built-in ARIA attributes including role="combobox" and aria-expanded
64+
- **Popup Management** - Automatic show/hide based on user interaction
65+
- **Signal-Based Reactivity** - Reactive state management using Angular signals
66+
67+
## Examples
68+
69+
### Autocomplete
70+
71+
An accessible input field that filters and suggests options as users type, helping them find and select values from a list.
72+
73+
<docs-tab-group>
74+
<docs-tab label="Basic">
75+
<docs-code-multifile preview hideCode path="adev/src/content/examples/aria/autocomplete/src/basic/app/app.ts">
76+
<docs-code header="app.ts" path="adev/src/content/examples/aria/autocomplete/src/basic/app/app.ts"/>
77+
<docs-code header="app.html" path="adev/src/content/examples/aria/autocomplete/src/basic/app/app.html"/>
78+
<docs-code header="app.css" path="adev/src/content/examples/aria/autocomplete/src/basic/app/app.css"/>
79+
</docs-code-multifile>
80+
</docs-tab>
81+
82+
<docs-tab label="Material">
83+
<docs-code-multifile preview hideCode path="adev/src/content/examples/aria/autocomplete/src/basic/material/app/app.ts">
84+
<docs-code header="app.ts" path="adev/src/content/examples/aria/autocomplete/src/basic/material/app/app.ts"/>
85+
<docs-code header="app.html" path="adev/src/content/examples/aria/autocomplete/src/basic/material/app/app.html"/>
86+
<docs-code header="app.css" path="adev/src/content/examples/aria/autocomplete/src/basic/material/app/app.css"/>
87+
</docs-code-multifile>
88+
</docs-tab>
89+
90+
<docs-tab label="Retro">
91+
<docs-code-multifile preview hideCode path="adev/src/content/examples/aria/autocomplete/src/basic/retro/app/app.ts">
92+
<docs-code header="app.ts" path="adev/src/content/examples/aria/autocomplete/src/basic/retro/app/app.ts"/>
93+
<docs-code header="app.html" path="adev/src/content/examples/aria/autocomplete/src/basic/retro/app/app.html"/>
94+
<docs-code header="app.css" path="adev/src/content/examples/aria/autocomplete/src/basic/retro/app/app.css"/>
95+
</docs-code-multifile>
96+
</docs-tab>
97+
</docs-tab-group>
98+
99+
Filtering is managed in user space by updating a signal that reactively filters the options list. Users navigate with arrow keys and select with Enter or click. This provides complete control and maximum flexibility for custom selection logic. See the [Autocomplete guide](guide/aria/autocomplete) for complete filtering patterns and examples.
100+
101+
### Readonly mode
102+
103+
A pattern that combines a readonly combobox with listbox to create single-selection dropdowns with keyboard navigation and screen reader support.
104+
105+
<docs-tab-group>
106+
<docs-tab label="Basic">
107+
<docs-code-multifile preview hideCode path="adev/src/content/examples/aria/select/src/icons/app/app.ts">
108+
<docs-code header="app.ts" path="adev/src/content/examples/aria/select/src/icons/app/app.ts"/>
109+
<docs-code header="app.html" path="adev/src/content/examples/aria/select/src/icons/app/app.html"/>
110+
<docs-code header="app.css" path="adev/src/content/examples/aria/select/src/icons/app/app.css"/>
111+
</docs-code-multifile>
112+
</docs-tab>
113+
114+
<docs-tab label="Material">
115+
<docs-code-multifile preview hideCode path="adev/src/content/examples/aria/select/src/icons/material/app/app.ts">
116+
<docs-code header="app.ts" path="adev/src/content/examples/aria/select/src/icons/material/app/app.ts"/>
117+
<docs-code header="app.html" path="adev/src/content/examples/aria/select/src/icons/material/app/app.html"/>
118+
<docs-code header="app.css" path="adev/src/content/examples/aria/select/src/icons/material/app/app.css"/>
119+
</docs-code-multifile>
120+
</docs-tab>
121+
122+
<docs-tab label="Retro">
123+
<docs-code-multifile preview hideCode path="adev/src/content/examples/aria/select/src/icons/retro/app/app.ts">
124+
<docs-code header="app.ts" path="adev/src/content/examples/aria/select/src/icons/retro/app/app.ts"/>
125+
<docs-code header="app.html" path="adev/src/content/examples/aria/select/src/icons/retro/app/app.html"/>
126+
<docs-code header="app.css" path="adev/src/content/examples/aria/select/src/icons/retro/app/app.css"/>
127+
</docs-code-multifile>
128+
</docs-tab>
129+
</docs-tab-group>
130+
131+
Triggering a dropdown without text input can be achieved using a button as the host trigger, or applying the native HTML `readonly` attribute to the input trigger. The popup opens on click or arrow keys.
132+
133+
This configuration provides the foundation for the [Select](guide/aria/select) and [Multiselect](guide/aria/multiselect) patterns. See those guides for complete dropdown implementations with triggers and overlay positioning.
134+
135+
### Datepicker grid
136+
137+
Combobox can coordinate with a two-dimensional grid to create accessible datepickers. Users navigate dates inside the calendar grid table using directional arrow keys and confirm selection with click, Enter, or Spacebar.
138+
139+
<docs-tab-group>
140+
<docs-tab label="Basic">
141+
<docs-code-multifile preview hideCode path="adev/src/content/examples/aria/combobox/src/datepicker/basic/app/app.ts">
142+
<docs-code header="app.ts" path="adev/src/content/examples/aria/combobox/src/datepicker/basic/app/app.ts"/>
143+
<docs-code header="app.html" path="adev/src/content/examples/aria/combobox/src/datepicker/basic/app/app.html"/>
144+
<docs-code header="app.css" path="adev/src/content/examples/aria/combobox/src/datepicker/basic/app/app.css"/>
145+
</docs-code-multifile>
146+
</docs-tab>
147+
148+
<docs-tab label="Material">
149+
<docs-code-multifile preview hideCode path="adev/src/content/examples/aria/combobox/src/datepicker/material/app/app.ts">
150+
<docs-code header="app.ts" path="adev/src/content/examples/aria/combobox/src/datepicker/material/app/app.ts"/>
151+
<docs-code header="app.html" path="adev/src/content/examples/aria/combobox/src/datepicker/material/app/app.html"/>
152+
<docs-code header="app.css" path="adev/src/content/examples/aria/combobox/src/datepicker/material/app/app.css"/>
153+
</docs-code-multifile>
154+
</docs-tab>
155+
156+
<docs-tab label="Retro">
157+
<docs-code-multifile preview hideCode path="adev/src/content/examples/aria/combobox/src/datepicker/retro/app/app.ts">
158+
<docs-code header="app.ts" path="adev/src/content/examples/aria/combobox/src/datepicker/retro/app/app.ts"/>
159+
<docs-code header="app.html" path="adev/src/content/examples/aria/combobox/src/datepicker/retro/app/app.html"/>
160+
<docs-code header="app.css" path="adev/src/content/examples/aria/combobox/src/datepicker/retro/app/app.css"/>
161+
</docs-code-multifile>
162+
</docs-tab>
163+
</docs-tab-group>
164+
165+
### Dialog popup
166+
167+
Dialog popups combine the combobox trigger with standard dialog layouts and focus traps (such as CDK's `cdkTrapFocus`). Use dialog popups when the overlay requires modal behavior or backdrop interaction.
168+
169+
<docs-tab-group>
170+
<docs-tab label="Basic">
171+
<docs-code-multifile preview hideCode path="adev/src/content/examples/aria/combobox/src/dialog/app/app.ts">
172+
<docs-code header="app.ts" path="adev/src/content/examples/aria/combobox/src/dialog/app/app.ts"/>
173+
<docs-code header="app.html" path="adev/src/content/examples/aria/combobox/src/dialog/app/app.html"/>
174+
<docs-code header="app.css" path="adev/src/content/examples/aria/combobox/src/dialog/app/app.css"/>
175+
</docs-code-multifile>
176+
</docs-tab>
177+
178+
<docs-tab label="Material">
179+
<docs-code-multifile preview hideCode path="adev/src/content/examples/aria/combobox/src/dialog/material/app/app.ts">
180+
<docs-code header="app.ts" path="adev/src/content/examples/aria/combobox/src/dialog/material/app/app.ts"/>
181+
<docs-code header="app.html" path="adev/src/content/examples/aria/combobox/src/dialog/material/app/app.html"/>
182+
<docs-code header="app.css" path="adev/src/content/examples/aria/combobox/src/dialog/material/app/app.css"/>
183+
</docs-code-multifile>
184+
</docs-tab>
185+
186+
<docs-tab label="Retro">
187+
<docs-code-multifile preview hideCode path="adev/src/content/examples/aria/combobox/src/dialog/retro/app/app.ts">
188+
<docs-code header="app.ts" path="adev/src/content/examples/aria/combobox/src/dialog/retro/app/app.ts"/>
189+
<docs-code header="app.html" path="adev/src/content/examples/aria/combobox/src/dialog/retro/app/app.html"/>
190+
<docs-code header="app.css" path="adev/src/content/examples/aria/combobox/src/dialog/retro/app/app.css"/>
191+
</docs-code-multifile>
192+
</docs-tab>
193+
</docs-tab-group>
194+
195+
## Testing
196+
197+
Angular Aria provides a `ComboboxHarness` for testing combobox components.
198+
Here is an example of how to use the harness in a component test:
199+
200+
```typescript
201+
import {ComponentFixture, TestBed} from '@angular/core/testing';
202+
import {HarnessLoader} from '@angular/cdk/testing';
203+
import {TestbedHarnessEnvironment} from '@angular/cdk/testing/testbed';
204+
import {ComboboxHarness} from '@angular/aria/combobox/testing';
205+
import {MyComboboxComponent} from './my-combobox'; // Your component
206+
207+
describe('MyComboboxComponent', () => {
208+
let fixture: ComponentFixture<MyComboboxComponent>;
209+
let loader: HarnessLoader;
210+
211+
beforeEach(async () => {
212+
TestBed.configureTestingModule({
213+
imports: [MyComboboxComponent],
214+
});
215+
216+
fixture = TestBed.createComponent(MyComboboxComponent);
217+
await fixture.whenStable();
218+
loader = TestbedHarnessEnvironment.loader(fixture);
219+
});
220+
221+
it('should allow opening and closing the popup', async () => {
222+
const combobox = await loader.getHarness(ComboboxHarness);
223+
224+
// Verify initial state
225+
expect(await combobox.isOpen()).toBe(false);
226+
227+
// Open the popup
228+
await combobox.open();
229+
expect(await combobox.isOpen()).toBe(true);
230+
231+
// Close the popup
232+
await combobox.close();
233+
expect(await combobox.isOpen()).toBe(false);
234+
});
235+
});
236+
```
237+
238+
## APIs
239+
240+
### Combobox Directive
241+
242+
Coordinates an interactive trigger element (such as a text input, button, or div) with a popup container.
243+
244+
#### Inputs / Model
245+
246+
| Property | Type | Default | Description |
247+
| ------------------ | ---------------------- | ------- | ------------------------------------------------------------------- |
248+
| `value` | `ModelSignal<string>` | `''` | Two-way bindable text value of the combobox |
249+
| `expanded` | `ModelSignal<boolean>` | `false` | Two-way bindable open/closed expanded state of the popup |
250+
| `disabled` | `boolean` | `false` | Disables the combobox trigger element |
251+
| `softDisabled` | `boolean` | `true` | Disables interaction while keeping the element keyboard focusable |
252+
| `alwaysExpanded` | `boolean` | `false` | Forces the popup to always remain open |
253+
| `inlineSuggestion` | `string \| undefined` | - | Sets an inline suggestion to be highlighted at the end of the input |
254+
| `tabIndex` | `number \| undefined` | - | Tabindex of the combobox element (aliased to `tabindex`) |
255+
256+
All keyboard events, focus coordination, and ARIA state properties (including `role="combobox"`, `aria-autocomplete`, and `aria-expanded`) are handled automatically on the host element.
257+
258+
---
259+
260+
### ComboboxPopup Directive
261+
262+
Marks an `<ng-template>` as the popup container for the combobox.
263+
264+
#### Inputs
265+
266+
| Property | Type | Default | Description |
267+
| ----------- | ------------------------------------------- | ----------- | ---------------------------------------------- |
268+
| `combobox` | `Combobox` | (Required) | Reference to the parent `Combobox` directive |
269+
| `popupType` | `'listbox' \| 'tree' \| 'grid' \| 'dialog'` | `'listbox'` | Specifies the layout/role profile of the popup |
270+
271+
---
272+
273+
### ComboboxWidget Directive
274+
275+
Connects the popup contents (such as a listbox or grid) with the parent combobox trigger.
276+
277+
#### Inputs
278+
279+
| Property | Type | Description |
280+
| ------------------ | --------------------- | ----------------------------------------------------------------------------------- |
281+
| `activeDescendant` | `string \| undefined` | The ID of the currently active option (bound to the active option ID in the widget) |
282+
283+
---
284+
285+
### Related patterns and directives
286+
287+
Combobox is the primitive directive for these documented patterns:
288+
289+
- **[Autocomplete](guide/aria/autocomplete)** - Filtering and suggestions pattern (coordinates input typing with options list)
290+
- **[Select](guide/aria/select)** - Single selection dropdown pattern (applied directly on non-editable button triggers)
291+
- **[Multiselect](guide/aria/multiselect)** - Multiple selection pattern (applied on non-editable triggers with multi-enabled Listbox)
292+
293+
Combobox typically combines with:
294+
295+
- **[Listbox](guide/aria/listbox)** - Most common popup content
296+
- **[Tree](guide/aria/tree)** - Hierarchical popup content (see Tree guide for examples)

0 commit comments

Comments
 (0)