Repeater
Repeat native field rows with stable identities and keyboard ordering.
stable · light DOM · 4.0.0. Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.
Live variants
default
No contacts added.
<j3w1-repeater id="example-repeater-default" max="10"><section class="repeater" aria-label="Additional contacts"><ol data-rows=""></ol><template data-row-template=""><li class="repeater-item"><label for="example-repeater-default-contact-name">Contact name</label><input class="repeater-control" id="example-repeater-default-contact-name" name="example-repeater-default-contact" required=""><div class="repeater-actions"><button class="repeater-control" type="button" data-move="-1">Move up</button><button class="repeater-control" type="button" data-move="1">Move down</button><button class="repeater-control" type="button" data-remove="">Remove</button></div></li></template><p data-empty="">No contacts added.</p><button class="repeater-control" type="button" data-add="" data-demo-focus-target="">Add contact</button><p role="status" data-repeater-status=""></p></section></j3w1-repeater>Install and register
Use the exact version. If npm publication is pending, install the release tarball from the installation guide.
npm install --save-exact @j3w1/ui@4.0.0import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/repeater.css';
import '@j3w1/ui/register/repeater';Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.
Copy the complete implementation
npx --package=@j3w1/ui@4.0.0 j3w1-ui copy repeater --out ./vendor/j3w1/repeaterThe CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.
Public API
attributes
| Name | Type / signature | Meaning |
|---|---|---|
disabled | CustomEvent | Disable the native controls owned by this instance. |
loading | CustomEvent | Mark the primary control busy and prevent duplicate activation. |
max | CustomEvent | Maximum rows, default 10; positive integer up to 100. |
properties
| Name | Type / signature | Meaning |
|---|---|---|
disabled | boolean | Delegates disabled state to native children. |
name | string | Native control name; application form keys remain explicit. |
rowIds | string[] | Stable IDs in current source order. Read only. |
methods
| Name | Type / signature | Meaning |
|---|---|---|
refresh | (): void | Reconnect behavior after replacing native child structure. |
focus | (options?: FocusOptions): void | Focus the first usable native control. |
add | (): string | null | Append a row when below the configured limit. |
remove | (id: string): void | Remove a known row and recover focus. |
move | (id: string, direction: number): void | Move a row one position up or down. |
events
| Name | Type / signature | Meaning |
|---|---|---|
j3w1-rows | CustomEvent | Row order or membership changed. |
Dependencies and verification
Registered components: none. Style dependencies: none.
Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.
Full implementation manifest, API and token dependency closure
Canonical specification
Repeater repeater
Repeat native field rows with stable identities and keyboard ordering.
Report an issue with this component
Tokens
Focus a role to inspect its values; follow its link for persistent usage and source details.
| Part | Role | Value | Use |
|---|---|---|---|
root.bg | color.surface.defaultapproveduse | #0d0707 | D-041 surface.default: color.primitive.modern.panel. |
root.text | color.text.defaultapproveduse | #e99499 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
root.border | color.border.controlapproveduse | #c81a1a | D-041 owner correction: red control and floating-frame borders, distinct from rose text. |
heading.text | color.text.brightapproveduse | #ffa2a7 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
secondary.text | color.text.mutedapproveduse | #d4868b | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
control.bg | color.surface.inputapproveduse | #000000 | Form-control fill. |
control.focus | color.interaction.focus.ringobserveduse | #e53935 | 1px dashed focus ring on controls and rows. |
button.bg | color.action.secondary.bgobserveduse | rgb(0 0 0 / 0%) | Secondary button has no fill. |
button.text | color.action.secondary.textapproveduse | #ffa2a7 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
button.border | color.action.secondary.borderapproveduse | #986f72 | D-041 action.secondary.border: color.primitive.modern.control. |
button.bg-hover | color.action.secondary.hover-bgobserveduse | #630f0d | Secondary button hover. |
button.bg-active | color.action.secondary.pressed-bgobserveduse | #420f0c | Secondary button pressed. |
button.border-active | color.border.activeobserveduse | #e53935 | Active or focused control border. |
button.focus | color.interaction.focus.ringobserveduse | #e53935 | 1px dashed focus ring on controls and rows. |
dependency.role-border-width-default | border.width.defaultobserveduse | 1px | Every border is 1px. |
dependency.role-color-border-disabled | color.border.disabledapproveduse | #482b2b | D-041 border.disabled: color.primitive.modern.divider. |
dependency.role-color-interaction-disabled-bg | color.interaction.disabled.bgapproveduse | #0d0707 | D-041 interaction.disabled.bg: color.primitive.modern.panel. |
dependency.role-color-text-disabled | color.text.disabledapproveduse | #a3676b | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
dependency.role-density-comfortable-control-height | density.comfortable.control-heightobserveduse | 32px | |
dependency.role-density-compact-control-height | density.compact.control-heightobserveduse | 24px | |
dependency.role-focus-offset | focus.offsetobserveduse | -2px | outline-offset for controls. |
dependency.role-radius-none | radius.noneobserveduse | 0px | The only radius. Nothing is rounded. |
dependency.role-space-12 | space.12observeduse | 12px | |
dependency.role-space-24 | space.24observeduse | 24px | |
dependency.role-space-8 | space.8observeduse | 8px |
State matrix
Every declared state and combination, statically rendered; the default cell is live. Sizes: compact, comfortable (switch with the density control above).
| State | Default |
|---|---|
default | No contacts added. |
empty | |
focus-visible | |
disabled |
Purpose
A variable number of the same native field row in one form; the host owns the fields, submission and persistence.
Anatomy
Parts as listed in the anatomy.
States
| State | Visual | Non-colour channel |
|---|---|---|
| default | named content on the default surface. Button controls are the secondary button (button.md); inputs keep the input look. | native text and structure |
| empty | a muted empty message | explicit text; Add stays |
| focus-visible | dashed focus ring | native focus position |
| disabled | disabled foreground, background and border at full opacity | native disabled state blocks activation |
Keyboard
As in the key table; nothing else is bound.
Accessibility
IDs and label and ARIA references are namespaced per row. Actions are named and keep their boundary when disabled. Removing a focused row moves focus to a surviving row or to Add; each explicit operation is announced.
Portability
Follows the shared component defaults in spec/portability.md (section
“Shared component defaults”).
Non-examples
Unlabelled controls. Colour-only status. Drag-only operations. Hidden required instructions. Stolen focus. An invented service success.
Contrast report
7 declared pairs measured on resolved sRGB values with the WCAG 2.x formula; 0 waived (decorative only), 0 failing. A pass is a design target for the named role, not an application-wide conformance claim.
| Pair | State | Kind | Foreground | Background | Ratio | Min | Result |
|---|---|---|---|---|---|---|---|
| repeater default text | default | text | color.text.default #e99499 | color.surface.default #0d0707 | 8.72 | 4.5 | pass |
| repeater default border | default | ui | color.border.control #c81a1a | color.surface.default #0d0707 | 3.44 | 3 | pass |
| Primary content | — | text | color.text.default #e99499 | color.surface.default #0d0707 | 8.72 | 4.5 | pass |
| Supporting content | — | text | color.text.muted #d4868b | color.surface.default #0d0707 | 7.22 | 4.5 | pass |
| Control boundary | — | ui | color.border.control #c81a1a | color.surface.default #0d0707 | 3.44 | 3 | pass |
| Button label | — | text | color.action.secondary.text #ffa2a7 | color.surface.default #0d0707 | 10.45 | 4.5 | pass |
| Button label on hover | — | text | color.action.secondary.text #ffa2a7 | color.action.secondary.hover-bg #630f0d | 6.84 | 4.5 | pass |
Keys
| Key | Action |
|---|---|
| Tab / Shift+Tab | Visit fields and row actions in source order. |
| Enter / Space | Add, remove or move a row. Focus follows the affected row or nearest survivor. |
For agents
Component JSON ·Implementation brief ·Build a task kit ·
Stress fixtures: FX-320 FX-360 FX-ZOOM-200 FX-I18N FX-RTL FX-RM FX-HC FX-TOUCH FX-DENSITY FX-STATE-MATRIX