[sdcorejs]

Summary

This is CH1, the first of three sd-chip PRs in the design handoff .sdcorejs/handoff/design-icon-chip-table/ (review of 22/10/2026 on 769f9ca, spec in chip.md). It fixes the behaviour and a11y issues A1–A8 and the specs D4, mostly by applying the fixes that already ship in sd-chip-calendar. No input, output or default changes, so it can ship as a patch. CH2 (input experience) and CH3 (visuals, cleanup, onSelect removal) follow in separate PRs.

The first commit adds the handoff bundle and the specs, which fail on their own. The second commit is the fix, npm run sync, the CHANGELOG, docs and the showcase.

What changed

Item	Before	After
A1	A removable predicate reached mat-chip-row as a function, which is always truthy. Backspace / Delete on a chip, or Backspace twice from the empty input, removed a locked chip.	Each chip gets its own boolean (isRemovable(item)), and onRemove checks it again.
A2	@if (item) hid 0 but still counted it. track $index rebuilt every chip after the removed one, so focus jumped.	chips() drops only null, undefined and ''. Chips are tracked by value.
A3	A model [1, 2] plus a typed “1” became [1, 2, '1'].	Duplicates compare as strings.
A4	Setting the model to null kept the chips and sent the old array.	null / undefined clears the chips and sets formControl to [].
A5	The outline used dirty || touched || submitted and the message used touched, so a submit without touching the field showed red with no message. Also aria-invalid="true" was set before any interaction.	One gate, isErrorShown(): invalid, and touched or the parent form submitted. It drives the outline, <mat-error>, the hideInlineError icon and aria-invalid.
A6	The ✕ (cancel) had no name, and sd-icon hid it with aria-hidden.	close icon named “Xoá {value}” (core.form.chip.remove, in vi/en/ja/ko/zh).
A7	The wrapper div was in the Tab order with no role or name, disabled included.	The wrapper is layout only. With sdViewDef, the face is a role="button" that Enter or Space opens. When disabled it leaves the Tab order and gets aria-disabled.
A8	With hideInlineError, the hidden error text had no id and the input had no aria-describedby. Two duplicate @if blocks.	One matSuffix element holds the icon and the hidden text (with errorId), and the input points aria-describedby at it.

Bug that was already on main (not in chip.md)

While checking “form reset to null” on the showcase, we found that mat-chip-grid writes back into the control on blur. As the value accessor of formControl, it waits for a setTimeout after every blur and then writes the text of the rendered chips into the control. The consequences:

• Number items became strings ([1, 2] → ['1', '2']) with no modelChange.
• A form reset made while the input had focus was undone.

The grid is now bound to its own gridControl, which nothing reads. It still needs an ngControl to compute its error state on every check. sd-chip marks the field touched when focus leaves it; moving between the input and the chips does not count. A side benefit is that Material's aria-invalid host binding no longer fights the A5 gate. The grid's required is set in code, because a [required] attribute on [formControl] would attach Angular's RequiredValidator to gridControl.

API consistency review

Following the mandatory naming and public API consistency review in AGENTS.md.

• Compared with:
  • sd-chip-calendar (same template and the source of the fixes): isErrorShown() and its gate, errorId, isRemovable(), removeLabel(), onViewKeydown, the view-trigger pattern, the close icon and the template @let _removable now match. The @let in sd-chip-calendar was renamed from _itemRemovable to _removable to match.
  • sd-date: same rule for when the error shows.
• Checked: input/output names and aliases, event payloads, defaults, two-way binding (model), public exports and entry points.
• Inputs and outputs: none added, renamed or retyped. No defaults changed.
• Behaviour change: model set to null / undefined now clears the chips and writes [] to formControl (A4). An untouched field with no model also holds [] instead of null.
• New public members (additive): errorId, chips, isErrorShown(), isRemovable(), removeLabel(), onViewKeydown, onFocusOut(), gridControl, chipGrid. Each name matches sd-chip-calendar wherever it has one.
• i18n: core.form.chip.remove ({value}) mirrors core.form.chip-calendar.remove ({date}). It is a separate key because the sd-chip-calendar strings name a day, which this one should not. Apps that supply a full custom I18nCatalog must add it, because the type is Record<I18nKey, string>.
• Public exports: unchanged. SdRemovableChipPipe is no longer used by the template but stays exported until CH3, which removes it as a breaking change.
• v19–v22: rolled out with npm run sync. npm run check:sync is green.
• Independent review: pending.

Deviations from chip.md

• Blur fix: the grid write-back fix above is outside the md, and was agreed before it was made.
• A5: the md describes the fix as a template binding. That was not enough, because MatChipInput binds aria-invalid = ngControl.invalid as a host binding. Giving the grid its own control solves it.
• A7: the view face also leaves the Tab order when disabled. The md does not mention this.
• A8: the md says to merge the two @if blocks. Merging them directly would break matSuffix projection, so the icon and the hidden text share one matSuffix wrapper instead.
• A2: chips() also drops exact duplicates from the display, because chips are tracked by value. The model is never rewritten.
• Dev-mode NG0956: replacing the whole chip list with different values now triggers this warning about track. That is the expected result of tracking by value, and sd-chip-calendar does the same.

Verification

All of this ran locally on exact Node 22.22.3:

• Karma v19 with coverage: npx ng test sdcorejs-angular --watch=false --browsers=ChromeHeadlessCI --code-coverage passes 7897/7897. Statements 90.01%, Branches 79.35%, Functions 90.64%, Lines 92.44%.
• v22 (Angular / Material 22.1.5): the chip, chip-calendar and form-generic specs pass 674/674.
• Other checks, all green:
  • npm run lint
  • npx ng build sdcorejs-angular
  • check:i18n, check:i18n-parity (1398 keys × 5 languages)
  • npm run test:theme, npm run check:scss-hex, npm run test:showcase-examples
  • npm run sync + npm run check:sync
• New specs: 27 cases in chip.behaviour.spec.ts, using real keydown, focus and submit events. Before the fix they failed (19, plus 2 for the blur write-back).
• Showcase (/forms/chip/examples, 768px light and dark):
  • Backspace twice and Delete do not remove the locked “Quản trị” chip.
  • The ✕ is named “Xoá Biên tập”.
  • A submit without touching shows message, outline and aria-invalid together.
  • The hideInlineError field points aria-describedby at the hidden text.
  • “Đặt lại” while the input has focus resets to null and untouched.

Not verified:

• Forced-colors mode.
• A real screen reader. Accessible names were checked in the DOM only.
• The 1280px layout. It was checked through the DOM only, because the preview pane scales it down too far to read.

v20 and v21 run in CI.

Showcase

• New section “Chip khoá” with a removable predicate.
• “Bắt buộc & số tối thiểu” is now a <form [formGroup]> with Gửi / Kiểm tra / Đặt lại buttons and a second hideInlineError field.
• demoSectionCount goes from 5 to 6, and the example sources were regenerated.

🤖 Generated with Claude Code