@ids-group-ltd/ids-design-system 0.10.3 → 0.11.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.
@@ -412,11 +412,73 @@ declare class ReserveMessagesDirective {
412
412
  static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ReserveMessagesDirective, "[dsReserveMessages]", never, {}, {}, never, never, true, never>;
413
413
  }
414
414
 
415
+ type FieldMessageState = 'default' | 'error' | 'warning' | 'success';
416
+
417
+ /**
418
+ * One validation error, structurally identical to Angular's signal-forms
419
+ * `ValidationError`.
420
+ *
421
+ * Declared here rather than imported from `@angular/forms/signals` on purpose:
422
+ * that module is `@experimental`, and a public DS type must not carry a
423
+ * dependency that can be renamed out from under consumers. Structural
424
+ * compatibility is all the interop needs — signal forms binds by input NAME and
425
+ * assigns its own `ValidationError[]`, which this shape accepts.
426
+ */
427
+ interface DsFieldError {
428
+ /** Identifies the kind of error, e.g. `required`, `minlength`, `server`. */
429
+ readonly kind: string;
430
+ /** Human-readable text. Authored by the consumer, at the validator. */
431
+ readonly message?: string;
432
+ }
433
+ /** What a field's `errors` input accepts before normalization. */
434
+ type DsFieldErrorsInput = string | DsFieldError | readonly DsFieldError[] | null | undefined;
435
+ /**
436
+ * The one reserved `DsFieldError.kind`. An error carrying it is advisory: it shows
437
+ * in the warning state and does NOT make the control invalid, which is how a form
438
+ * model can raise a non-blocking remark — Angular's own `AbstractControl` has no
439
+ * channel for one, only `errors` and the validity derived from it.
440
+ */
441
+ declare const DS_FIELD_WARNING_KIND = "warning";
442
+ /** The single line a field shows below itself, already resolved. */
443
+ interface DsFieldMessage {
444
+ readonly text: string;
445
+ readonly state: FieldMessageState;
446
+ }
447
+
415
448
  type ButtonColor = 'primary' | 'secondary' | 'tertiary' | 'neutral' | 'error' | 'success' | 'warning';
416
449
  type ButtonVariant = 'solid' | 'tonal' | 'ghost' | 'outline' | 'text';
417
450
  type ButtonType = 'button' | 'submit' | 'reset';
418
451
 
419
- declare class ButtonComponent {
452
+ /**
453
+ * The inputs of anything that renders a `ds-field-message` line — the message half
454
+ * of a field, split out so `ds-button` can take it without also taking `errors`,
455
+ * `invalid` and `touched`, which describe a form control's validation state and
456
+ * mean nothing on a button.
457
+ *
458
+ * `@Directive()` is required, not decoration: Angular refuses to compile a base
459
+ * class that declares inputs without it.
460
+ */
461
+ declare abstract class DsMessageBase {
462
+ /** Helper text shown below the control. */
463
+ readonly hint: _angular_core.InputSignalWithTransform<string, string | null | undefined>;
464
+ /** Error text. Shown immediately — binding it says the consumer has already
465
+ * decided this is in error. Takes precedence over `errors`. */
466
+ readonly error: _angular_core.InputSignalWithTransform<string, string | null | undefined>;
467
+ /** Advisory text, shown when there is no error. */
468
+ readonly warning: _angular_core.InputSignalWithTransform<string, string | null | undefined>;
469
+ /** Reserve the message-row height even when empty, so the control doesn't shift
470
+ * the layout below it when a hint/error appears. Falls back to
471
+ * `DS_CONFIG.field.reserveMessage`, then off. */
472
+ readonly reserveMessage: _angular_core.InputSignalWithTransform<boolean | null, unknown>;
473
+ /** Glyph on the message line, overriding what the state resolves to. Unset
474
+ * follows `DS_CONFIG.field.stateIcons`; `false` removes the glyph here alone. */
475
+ readonly messageIcon: _angular_core.InputSignal<false | IconName | null>;
476
+ readonly reserveMessageResolved: _angular_core.Signal<boolean>;
477
+ static ɵfac: _angular_core.ɵɵFactoryDeclaration<DsMessageBase, never>;
478
+ static ɵdir: _angular_core.ɵɵDirectiveDeclaration<DsMessageBase, never, never, { "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "error": { "alias": "error"; "required": false; "isSignal": true; }; "warning": { "alias": "warning"; "required": false; "isSignal": true; }; "reserveMessage": { "alias": "reserveMessage"; "required": false; "isSignal": true; }; "messageIcon": { "alias": "messageIcon"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
479
+ }
480
+
481
+ declare class ButtonComponent extends DsMessageBase {
420
482
  /** Segment of a ds-field-group: the group owns the border, radius and focus
421
483
  * ring, so .in-group strips this control back to its bare contents. */
422
484
  protected readonly inGroup: boolean;
@@ -458,6 +520,21 @@ declare class ButtonComponent {
458
520
  /** ARIA `aria-controls`, forwarded to the inner <button> — the id of the panel
459
521
  * this button opens, e.g. `ds-app-layout`'s `railId`. */
460
522
  readonly ariaControls: _angular_core.InputSignal<string | null>;
523
+ /** Why the button is refused, shown as its second line. Read only while
524
+ * `disabled` — a greyed control that does not say why is a dead end.
525
+ *
526
+ * Setting it also changes HOW the button is disabled: it takes `aria-disabled`
527
+ * instead of the native attribute, because a natively disabled button cannot be
528
+ * focused and the reason would never be announced. The click is swallowed in
529
+ * `onClick` instead. Leave it unset and nothing changes.
530
+ *
531
+ * Length is deliberately not capped: the text wraps and the button grows. Same
532
+ * name and meaning as `TableRowAction.disabledReason`. */
533
+ readonly disabledReason: _angular_core.InputSignalWithTransform<string, string | null | undefined>;
534
+ /** ARIA `aria-describedby` — point the button at a description the app renders
535
+ * itself, such as a `ds-field-message` under a form. Merged with the id of
536
+ * `disabledReason` when both are present. */
537
+ readonly ariaDescribedBy: _angular_core.InputSignal<string | null>;
461
538
  /** Fires on click, unless `disabled` or `loading`. */
462
539
  readonly pressed: _angular_core.OutputEmitterRef<MouseEvent>;
463
540
  /** The inner native <button>, exposed so overlay triggers can position
@@ -465,10 +542,18 @@ declare class ButtonComponent {
465
542
  * `(pressed)="pop.toggle(trigger.buttonRef().nativeElement)"`. */
466
543
  readonly buttonRef: _angular_core.Signal<ElementRef<HTMLButtonElement>>;
467
544
  protected readonly classes: _angular_core.Signal<string>;
545
+ protected readonly softDisabled: _angular_core.Signal<boolean>;
546
+ private readonly uid;
547
+ protected readonly reasonId: string;
548
+ protected readonly hintId: _angular_core.Signal<string | null>;
549
+ protected readonly describedBy: _angular_core.Signal<string | null>;
550
+ protected readonly hasMessageRow: _angular_core.Signal<boolean>;
551
+ private readonly fieldMessage;
552
+ protected readonly message: _angular_core.Signal<DsFieldMessage>;
468
553
  constructor();
469
554
  protected onClick(event: MouseEvent): void;
470
555
  static ɵfac: _angular_core.ɵɵFactoryDeclaration<ButtonComponent, never>;
471
- static ɵcmp: _angular_core.ɵɵComponentDeclaration<ButtonComponent, "ds-button", never, { "color": { "alias": "color"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "fullWidth": { "alias": "fullWidth"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "trailingIcon": { "alias": "trailingIcon"; "required": false; "isSignal": true; }; "ariaHasPopup": { "alias": "ariaHasPopup"; "required": false; "isSignal": true; }; "ariaExpanded": { "alias": "ariaExpanded"; "required": false; "isSignal": true; }; "ariaControls": { "alias": "ariaControls"; "required": false; "isSignal": true; }; }, { "pressed": "pressed"; }, never, ["*", "[dsButtonSubtext]"], true, never>;
556
+ static ɵcmp: _angular_core.ɵɵComponentDeclaration<ButtonComponent, "ds-button", never, { "color": { "alias": "color"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "fullWidth": { "alias": "fullWidth"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "trailingIcon": { "alias": "trailingIcon"; "required": false; "isSignal": true; }; "ariaHasPopup": { "alias": "ariaHasPopup"; "required": false; "isSignal": true; }; "ariaExpanded": { "alias": "ariaExpanded"; "required": false; "isSignal": true; }; "ariaControls": { "alias": "ariaControls"; "required": false; "isSignal": true; }; "disabledReason": { "alias": "disabledReason"; "required": false; "isSignal": true; }; "ariaDescribedBy": { "alias": "ariaDescribedBy"; "required": false; "isSignal": true; }; }, { "pressed": "pressed"; }, never, ["*", "[dsButtonSubtext]"], true, never>;
472
557
  }
473
558
 
474
559
  /** A single binary toggle button (pressed / not pressed) with an optional
@@ -500,6 +585,11 @@ declare class IconButtonComponent {
500
585
  readonly icon: _angular_core.InputSignal<IconName>;
501
586
  /** Accessible name — required since the button has no visible text. */
502
587
  readonly ariaLabel: _angular_core.InputSignal<string>;
588
+ /** ARIA `aria-describedby` — the id of text the app renders beside the button,
589
+ * such as why the action is refused. Icon-only leaves no room for a second
590
+ * line, so unlike `ds-button` there is no `disabledReason` here: the text has
591
+ * to exist on screen already for this to point at it. */
592
+ readonly ariaDescribedBy: _angular_core.InputSignal<string | null>;
503
593
  /** Fill style — standard (chromeless), filled, tonal, or outlined. */
504
594
  readonly variant: _angular_core.InputSignal<IconButtonVariant>;
505
595
  /** Brand/status hue family (shared with ds-button). `variant` is the fill
@@ -528,7 +618,7 @@ declare class IconButtonComponent {
528
618
  protected readonly iconSize: _angular_core.Signal<16 | 24 | 20>;
529
619
  protected onClick(event: MouseEvent): void;
530
620
  static ɵfac: _angular_core.ɵɵFactoryDeclaration<IconButtonComponent, never>;
531
- static ɵcmp: _angular_core.ɵɵComponentDeclaration<IconButtonComponent, "ds-icon-button", never, { "icon": { "alias": "icon"; "required": true; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": true; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "selected": { "alias": "selected"; "required": false; "isSignal": true; }; "ariaExpanded": { "alias": "ariaExpanded"; "required": false; "isSignal": true; }; "ariaControls": { "alias": "ariaControls"; "required": false; "isSignal": true; }; }, { "pressed": "pressed"; }, never, never, true, never>;
621
+ static ɵcmp: _angular_core.ɵɵComponentDeclaration<IconButtonComponent, "ds-icon-button", never, { "icon": { "alias": "icon"; "required": true; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": true; "isSignal": true; }; "ariaDescribedBy": { "alias": "ariaDescribedBy"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "selected": { "alias": "selected"; "required": false; "isSignal": true; }; "ariaExpanded": { "alias": "ariaExpanded"; "required": false; "isSignal": true; }; "ariaControls": { "alias": "ariaControls"; "required": false; "isSignal": true; }; }, { "pressed": "pressed"; }, never, never, true, never>;
532
622
  }
533
623
 
534
624
  declare class BadgeComponent {
@@ -1320,39 +1410,6 @@ declare class TabsComponent {
1320
1410
  static ɵcmp: _angular_core.ɵɵComponentDeclaration<TabsComponent, "ds-tabs", never, { "selectedIndex": { "alias": "selectedIndex"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "lazy": { "alias": "lazy"; "required": false; "isSignal": true; }; "scrollable": { "alias": "scrollable"; "required": false; "isSignal": true; }; "closable": { "alias": "closable"; "required": false; "isSignal": true; }; "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "urlParam": { "alias": "urlParam"; "required": false; "isSignal": true; }; "rememberLastTab": { "alias": "rememberLastTab"; "required": false; "isSignal": true; }; }, { "selectedIndex": "selectedIndexChange"; "tabClosed": "tabClosed"; }, ["tabs"], never, true, never>;
1321
1411
  }
1322
1412
 
1323
- type FieldMessageState = 'default' | 'error' | 'warning' | 'success';
1324
-
1325
- /**
1326
- * One validation error, structurally identical to Angular's signal-forms
1327
- * `ValidationError`.
1328
- *
1329
- * Declared here rather than imported from `@angular/forms/signals` on purpose:
1330
- * that module is `@experimental`, and a public DS type must not carry a
1331
- * dependency that can be renamed out from under consumers. Structural
1332
- * compatibility is all the interop needs — signal forms binds by input NAME and
1333
- * assigns its own `ValidationError[]`, which this shape accepts.
1334
- */
1335
- interface DsFieldError {
1336
- /** Identifies the kind of error, e.g. `required`, `minlength`, `server`. */
1337
- readonly kind: string;
1338
- /** Human-readable text. Authored by the consumer, at the validator. */
1339
- readonly message?: string;
1340
- }
1341
- /** What a field's `errors` input accepts before normalization. */
1342
- type DsFieldErrorsInput = string | DsFieldError | readonly DsFieldError[] | null | undefined;
1343
- /**
1344
- * The one reserved `DsFieldError.kind`. An error carrying it is advisory: it shows
1345
- * in the warning state and does NOT make the control invalid, which is how a form
1346
- * model can raise a non-blocking remark — Angular's own `AbstractControl` has no
1347
- * channel for one, only `errors` and the validity derived from it.
1348
- */
1349
- declare const DS_FIELD_WARNING_KIND = "warning";
1350
- /** The single line a field shows below itself, already resolved. */
1351
- interface DsFieldMessage {
1352
- readonly text: string;
1353
- readonly state: FieldMessageState;
1354
- }
1355
-
1356
1413
  /**
1357
1414
  * The inputs every DS form field has, declared once.
1358
1415
  *
@@ -1361,17 +1418,11 @@ interface DsFieldMessage {
1361
1418
  * lifting them would hand a checkbox a `success` or a slider a `label` it never
1362
1419
  * had — a silent public-API addition.
1363
1420
  *
1364
- * `@Directive()` is required, not decoration: Angular refuses to compile a base
1365
- * class that declares inputs without it.
1421
+ * The message half lives one level up in `DsMessageBase`, which anything with a
1422
+ * message line can take. What stays here is the validation state a form control
1423
+ * has and a plain control does not.
1366
1424
  */
1367
- declare abstract class DsFieldBase {
1368
- /** Helper text shown below the field. */
1369
- readonly hint: _angular_core.InputSignalWithTransform<string, string | null | undefined>;
1370
- /** Error text. Shown immediately — binding it says the consumer has already
1371
- * decided this field is in error. Takes precedence over `errors`. */
1372
- readonly error: _angular_core.InputSignalWithTransform<string, string | null | undefined>;
1373
- /** Advisory text, shown when there is no error. */
1374
- readonly warning: _angular_core.InputSignalWithTransform<string, string | null | undefined>;
1425
+ declare abstract class DsFieldBase extends DsMessageBase {
1375
1426
  /** Validation errors, shown once the user has interacted. Bound automatically
1376
1427
  * by signal forms; reactive and template-driven forms are read through
1377
1428
  * `NgControl` and need nothing here. Accepts a string, one error, or an array. */
@@ -1383,18 +1434,8 @@ declare abstract class DsFieldBase {
1383
1434
  /** Whether the user has interacted with the field. Bound by signal forms; gates
1384
1435
  * `errors`, so a `required` error does not greet an untouched form. */
1385
1436
  readonly touched: _angular_core.InputSignalWithTransform<boolean, unknown>;
1386
- /** Reserve the message-row height even when empty, so the field doesn't shift
1387
- * the layout below it when a hint/error appears. Falls back to
1388
- * `DS_CONFIG.field.reserveMessage`, then off — opt in per field, or app-wide
1389
- * for a form that shows validation messages. */
1390
- readonly reserveMessage: _angular_core.InputSignalWithTransform<boolean | null, unknown>;
1391
- /** Glyph on the message line, overriding what the state resolves to. Unset
1392
- * follows `DS_CONFIG.field.stateIcons`; `false` removes the glyph on this field
1393
- * alone. */
1394
- readonly messageIcon: _angular_core.InputSignal<false | IconName | null>;
1395
- readonly reserveMessageResolved: _angular_core.Signal<boolean>;
1396
1437
  static ɵfac: _angular_core.ɵɵFactoryDeclaration<DsFieldBase, never>;
1397
- static ɵdir: _angular_core.ɵɵDirectiveDeclaration<DsFieldBase, never, never, { "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "error": { "alias": "error"; "required": false; "isSignal": true; }; "warning": { "alias": "warning"; "required": false; "isSignal": true; }; "errors": { "alias": "errors"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "touched": { "alias": "touched"; "required": false; "isSignal": true; }; "reserveMessage": { "alias": "reserveMessage"; "required": false; "isSignal": true; }; "messageIcon": { "alias": "messageIcon"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
1438
+ static ɵdir: _angular_core.ɵɵDirectiveDeclaration<DsFieldBase, never, never, { "errors": { "alias": "errors"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "touched": { "alias": "touched"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
1398
1439
  }
1399
1440
 
1400
1441
  /**
@@ -2031,8 +2072,26 @@ interface TableColumn<T = unknown> {
2031
2072
  * colour and underline while the row is hovered. Only has an effect on a
2032
2073
  * `rowInteractive` table: on a passive one every hover treatment is suppressed on
2033
2074
  * purpose, so a tint cannot promise a click that does not happen. Style it with
2034
- * `--ds-table-cell-link-color` / `--ds-table-cell-link-decoration`. */
2075
+ * `--ds-table-cell-link-color` / `--ds-table-cell-link-decoration`.
2076
+ *
2077
+ * Prefer `link` where the row leads somewhere: a tint appears only on hover, which
2078
+ * a keyboard or touch user never sees. */
2035
2079
  interactive?: boolean;
2080
+ /** Renders this column's value as a real `<a>`, which is the accessible way to say
2081
+ * a row leads somewhere: it is visible without hovering, lands in the tab order as
2082
+ * a link rather than as a table row, and opens in a new tab on Ctrl/Cmd-click —
2083
+ * none of which a clickable `<tr>` can offer.
2084
+ *
2085
+ * Return an Angular route target (a string, or the array form for dynamic
2086
+ * segments); `null` / `undefined` leaves that row's cell as plain text, so a list
2087
+ * where only some rows are reachable needs no second column. For an external URL,
2088
+ * render the cell through a `[cell]` template instead — this takes route targets
2089
+ * only, and the router is touched at all only once a column sets `link`.
2090
+ *
2091
+ * Composes with `rowInteractive`: the link stops its own click from reaching the
2092
+ * row, so the row handler fires for the rest of the row and the link navigates
2093
+ * once. Style it with the same `--ds-table-cell-link-*` tokens as `interactive`. */
2094
+ link?: (row: T) => string | readonly unknown[] | null | undefined;
2036
2095
  /** Initial visibility: start hidden. The column picker (or a bound
2037
2096
  * `hiddenKeys` set) owns the state from then on; a hidden column stays
2038
2097
  * available to `filterable` matching and sorting. */
@@ -2592,6 +2651,7 @@ declare class TableComponent<T extends object> {
2592
2651
  protected headerClasses(col: TableColumn<T>): string;
2593
2652
  protected sortIcon(col: TableColumn<T>): 'sortAsc' | 'sortDesc' | 'sort';
2594
2653
  protected cellValue(row: T, col: TableColumn<T>): string;
2654
+ protected cellLink(row: T, col: TableColumn<T>): string | readonly unknown[] | null;
2595
2655
  /** Serialises the visible columns of the rows the TABLE HOLDS as a CSV download.
2596
2656
  * On a server-paged table that is one page — prefer `runExport()`, which goes
2597
2657
  * through `exportFetcher` and exports the whole set. Pass `rows` to serialise a
@@ -3244,6 +3304,13 @@ declare class SidenavComponent implements SidenavContract {
3244
3304
  * "A" tile beside the "MyAdmin" wordmark). Empty = first letter of `brand`;
3245
3305
  * unset falls back to `DS_CONFIG.brand.logoLetter`. */
3246
3306
  readonly logoLetter: _angular_core.InputSignal<string | null>;
3307
+ /** Route the brand row links to — typically the app's home. Unset leaves the row a
3308
+ * plain, non-interactive block. Router targets only, and `RouterLink` is
3309
+ * instantiated only once this is set, so an app with no router still renders. */
3310
+ readonly brandRoute: _angular_core.InputSignal<string | readonly unknown[] | null>;
3311
+ /** Accessible name for the brand link; unset names it "<brand>, home". Ignored
3312
+ * while `brandRoute` is unset. */
3313
+ readonly brandLinkLabel: _angular_core.InputSignal<string | null>;
3247
3314
  /** The template must read THIS, never the input beside it — that one is null
3248
3315
  * until bound, and the config default lives here. */
3249
3316
  readonly brandName: _angular_core.Signal<string>;
@@ -3255,8 +3322,9 @@ declare class SidenavComponent implements SidenavContract {
3255
3322
  * starting with an astral character (an emoji, a rarer CJK glyph) yields half
3256
3323
  * a surrogate pair and paints as tofu. */
3257
3324
  protected readonly markGlyph: _angular_core.Signal<string>;
3325
+ protected readonly brandAriaLabel: _angular_core.Signal<string>;
3258
3326
  static ɵfac: _angular_core.ɵɵFactoryDeclaration<SidenavComponent, never>;
3259
- static ɵcmp: _angular_core.ɵɵComponentDeclaration<SidenavComponent, "ds-sidenav", never, { "collapsed": { "alias": "collapsed"; "required": false; "isSignal": true; }; "rail": { "alias": "rail"; "required": false; "isSignal": true; }; "brand": { "alias": "brand"; "required": false; "isSignal": true; }; "logoLetter": { "alias": "logoLetter"; "required": false; "isSignal": true; }; }, {}, ["brandNameRef"], ["[brand]", "[dsBrandName]", "*"], true, never>;
3327
+ static ɵcmp: _angular_core.ɵɵComponentDeclaration<SidenavComponent, "ds-sidenav", never, { "collapsed": { "alias": "collapsed"; "required": false; "isSignal": true; }; "rail": { "alias": "rail"; "required": false; "isSignal": true; }; "brand": { "alias": "brand"; "required": false; "isSignal": true; }; "logoLetter": { "alias": "logoLetter"; "required": false; "isSignal": true; }; "brandRoute": { "alias": "brandRoute"; "required": false; "isSignal": true; }; "brandLinkLabel": { "alias": "brandLinkLabel"; "required": false; "isSignal": true; }; }, {}, ["brandNameRef"], ["[brand]", "[dsBrandName]", "*"], true, never>;
3260
3328
  }
3261
3329
 
3262
3330
  declare class SidenavGroupComponent {
@@ -4857,6 +4925,7 @@ declare class CheckboxComponent extends DsBooleanControlValueAccessor {
4857
4925
  private readonly fieldMessage;
4858
4926
  protected readonly message: _angular_core.Signal<DsFieldMessage>;
4859
4927
  protected readonly invalidResolved: _angular_core.Signal<boolean>;
4928
+ protected readonly controlState: _angular_core.Signal<FieldMessageState | null>;
4860
4929
  protected readonly fieldClass: _angular_core.Signal<string>;
4861
4930
  protected onCheckedChange(event: Event): void;
4862
4931
  static ɵfac: _angular_core.ɵɵFactoryDeclaration<CheckboxComponent, never>;
@@ -4949,6 +5018,7 @@ declare class RadioGroupComponent extends DsControlValueAccessor<unknown> implem
4949
5018
  private readonly fieldMessage;
4950
5019
  protected readonly message: _angular_core.Signal<DsFieldMessage>;
4951
5020
  protected readonly invalidResolved: _angular_core.Signal<boolean>;
5021
+ protected readonly controlState: _angular_core.Signal<FieldMessageState | null>;
4952
5022
  private readonly radios;
4953
5023
  private get enabledRadios();
4954
5024
  isTabbable(radio: RadioGroupChild): boolean;
@@ -1,273 +0,0 @@
1
- # Authoring migration manifests
2
-
3
- How to write a `migrations/<version>.json` entry so it is complete, unambiguous, and safely
4
- executable by **both** consumers of these files: a machine transform / grep, and an LLM agent whose
5
- work a human then reviews. (Nx's `--agentic` runner — which delegates judgment migrations to an
6
- installed AI agent, Claude Code included — is the closest industry precedent; this is a real pattern,
7
- not a bespoke one.) Schema and field reference live in `README.md`; this file is the *how to write it
8
- well* companion. The prose `CHANGELOG.md` stays the human source of truth — a manifest is its machine
9
- mirror; if they disagree, fix the manifest.
10
-
11
- ## The one rule everything else serves
12
-
13
- **A reader (machine or agent) must be able to act on an entry without seeing the prose changelog,
14
- and know exactly where it does and does NOT apply.** Every rule below is in service of that.
15
-
16
- ## Granularity & ordering
17
-
18
- - **One entry per mechanical unit, not per changelog bullet.** A bullet that renames a component AND
19
- its types AND its tokens becomes several entries (one selector-rename, N type-renames, one
20
- token-rename). A finder/applier acts on one unit; a reviewer rejects one unit.
21
- - **Split a compound behavioral bullet only where the sub-changes migrate differently.** Keep one
22
- `behavior` entry when the steps are one coherent action.
23
- - **Substring-collision ordering.** We match by grep + token boundary + LLM, NOT by AST — so a naive
24
- replace of a short identifier can corrupt a longer one that contains it (`DropdownOption` inside
25
- `DropdownOptionGroup`). No industry manifest has a "longer-first" field (real engines match whole
26
- AST nodes). Our mitigation: give the longer identifier its **own entry**, and in the shorter one's
27
- `note` say *"rename the longer identifier first"*. Never rely on replace order alone.
28
-
29
- ## Precision
30
-
31
- - **Exact identifiers, never a paraphrase.** `old`/`new` and `searchHints` carry the string exactly
32
- as it appears in consumer code (`--ds-pagehdr-title-fs`, not "the page-header title token").
33
- - **Closed enumerated lists for removals.** Name every removed symbol; "some deprecated tokens" is a
34
- defect.
35
- - **Bound every pattern.** If `old` is a prefix/pattern (`--ds-*-bg`), state the boundary in `note`:
36
- what it covers AND what it excludes (e.g. "DS tokens only — a consumer's own `-bg` variable is not
37
- affected; confirm the new name exists in the installed package when unsure").
38
- - **State what is NOT affected** whenever an attribute/class/type name is shared with other
39
- components — this is the same instinct as element-scoping, written for the human reviewer.
40
-
41
- ## Scope (the false-positive guard)
42
-
43
- - **Element-scope in `old` itself**, never in prose: `element[attr]` (e.g. `ds-button[variant]`).
44
- This is our lightweight `limitedTo` — it tells the finder/recheck to count matches only on that
45
- element, so a shared attribute name (`variant` on `ds-badge`, `ds-select`, …) never false-positives.
46
- - A plain identifier / selector / token / type has no element scope → it matches everywhere; don't
47
- add a fake scope.
48
-
49
- ## `searchHints` are broad recall seeds — do NOT over-anchor them
50
-
51
- `searchHints` exist to help the finder *locate candidates*; precision comes from the `old` field
52
- (`element[attr]` scope) plus the finder confirming each hit's enclosing element and the recheck's
53
- scoped grep — NOT from a narrow hint. So keep hints broad enough for recall, even if they match
54
- non-target occurrences the finder will later drop:
55
-
56
- - **Attribute-value items**: hint the bare attribute (`variant="`, `size="`), NOT the element+attribute
57
- together. Angular tags routinely span lines (`<ds-button⏎ variant="…">`), so an element-anchored
58
- hint like `ds-button variant=` would MISS the multi-line cases the bare hint catches. The
59
- element scope lives in `old`, and the finder walks up to confirm the enclosing element.
60
- - **Token-pattern items**: don't anchor to `--ds-` when non-`--ds-` DS-owned globals are in scope.
61
- (The `--*-bg` rename also renames `--select-bg` / `--chart-*-bg` / `--status-*-bg`, which have no
62
- `--ds-` prefix — a `--ds-`-anchored hint would silently miss them.) Carry the precision in the
63
- `note` (what's DS-owned vs the consumer's own vars), not in a narrowed hint.
64
-
65
- Rule of thumb: a hint that risks a false *negative* (missed usage) is worse than one that risks a
66
- false *positive* (the finder/recheck discard those cheaply).
67
-
68
- ## Detectability (the false-NEGATIVE guard): `surface`, `detect`, `verify`
69
-
70
- The scope rules above stop an item matching code it does not own. These stop the opposite, which is
71
- worse because it is silent: an entry that is correct, complete, unambiguous — and locates nothing.
72
-
73
- mm-broker walked 0.6.0 → 0.10.1 with this plugin (2026-08-21) and a review afterwards found two
74
- entries the loop had passed over without a word. Both are worth knowing by heart, because neither
75
- looks defective:
76
-
77
- > `0.7.1#table-sortkey-non-null-when-unsorted` — `old: "ds-table[sortKey]"`, hints `sortKey`,
78
- > `sortDir`, `sortChange`. The code that breaks is the consumer's OWN store:
79
- > `sorting: store.sortKey() ? { path: store.sortKey()!, order: store.sortDir() ?? 'Asc' } : undefined`.
80
- > It binds no `sortKey` on the element — nobody does; the key arrives through `(sortChange)` — so the
81
- > element-scoped `old` matched **nowhere**, the finder returned zero hits, the orchestrator recorded
82
- > *not applicable*, and the recheck's clean grep CONFIRMED that verdict. Three server-paged screens
83
- > kept ordering by a column whose header showed no sort.
84
-
85
- > `0.7.1#field-reserve-message-default-off` — the sentence that mattered ("consumers that had
86
- > written `[reserveMessage]="false"` to opt OUT can delete those bindings") sat at word 150 of a
87
- > 200-word note, with no delete entry to act on. Three dead bindings survived the upgrade.
88
-
89
- - **`surface` is required on every item, and `none` is an answer.** Say which artifact of the
90
- consumer's changes: `template`, `typescript`, `style`, `config`, or `none` when the only action is
91
- to look at a screen. An array is legal where a change genuinely spans two (`["template",
92
- "typescript"]` for a value remap whose values also come from a typed field). A missing `surface`
93
- and a deliberate `none` must never read the same to a finder — that ambiguity is what let a
94
- TypeScript-surface item be searched as a template item.
95
- - **`detect` carries the CONSUMER's shapes, not ours.** Once a `behavior` item's surface reaches
96
- their `typescript` or their app `config`, `old` and `searchHints` stop being enough: our symbol
97
- names appear in their templates and not in the logic that has to change. (A `style` surface is the
98
- exception — in a stylesheet they write our token names verbatim, so `--ds-search-height` is already
99
- the locator.) Write the shapes the way they write them —
100
- `orderBy: sortKey`, `sortKey() ?`, `?? config.control?.size`, `protected clear(` — and expect them
101
- to be imperfect; they are recall seeds for a semantic pass, not a find/replace.
102
- - **`verify` is the positive assertion.** For a rename, "the old name is gone" is proof. For a
103
- behaviour change there was never a symbol to remove, so the recheck has nothing to grep and
104
- reports success by default. Give it the sentence it can actually test: *"every place that turns
105
- (sortChange) into a query gates on the direction, not the key"*. If you cannot write that sentence,
106
- the item is not yet understood well enough to ship.
107
- - **A missing item is worse than a noisy one.** The scope rules trade a false positive for cheap
108
- discard work; these trade a false negative for the same. When in doubt, name the surface widely and
109
- let the semantic pass narrow it.
110
-
111
- ## Supersession: name the item you reverse
112
-
113
- A default flipped in one release and flipped back in the next reads as two independent instructions,
114
- and a consumer walking the chain does the first release's work and then undoes it — or, if they skip
115
- a version (0.9.0 was skipped entirely by one consumer going 0.8.0 → 0.9.1), acts on guidance that no
116
- longer holds. `0.8.0#table-client-sort-replaced-by-sort-mode` told consumers unset now resolves to
117
- `'client'` and that a server-paged table must declare `"server"`; `0.9.0#table-sort-filter-mode-default-server`
118
- made unset mean `'server'` again.
119
-
120
- So the later item carries `supersedes: ["0.8.0#table-client-sort-replaced-by-sort-mode"]` and the
121
- earlier one `supersededBy: ["0.9.0#table-sort-filter-mode-default-server"]`. Both directions, because
122
- both readers exist. `tools/migration-lint.mjs` resolves every reference, so a typo or a renamed id
123
- fails the release rather than pointing at nothing.
124
-
125
- ## `value-remap` map conventions
126
-
127
- - **Key = old VALUE. Value = the FULL replacement of the whole `attr="oldValue"` token** (or `null`
128
- to drop the attribute). Never a bare value — that makes the applier guess.
129
- - value→value: `{ "secondary": "variant=\"tonal\"" }`
130
- - value→different attribute: `{ "outline": "color=\"neutral\" variant=\"outline\"" }`
131
- - value→becomes default (drop): `{ "primary": null }`
132
- - value→becomes a bare boolean attribute: `{ "indeterminate": "indeterminate" }`
133
- - **Passthrough-by-omission (the universal convention).** A value the changelog does NOT change is
134
- simply ABSENT from the map — the applier and recheck leave it untouched, never guess. Only
135
- enumerate values the changelog actually addresses.
136
- - **Identity = still valid.** A value that stays valid maps to its own full token
137
- (`{ "text": "variant=\"text\"" }`); the recheck treats it as valid, not as "old to remove".
138
- - **Dynamic bindings.** If the changelog moves values to a different attribute, say in `note` that
139
- `[attr]="expr"` bindings and any method/field/type supplying old values must be rebound/retyped too.
140
-
141
- ## Default-value changes get their OWN entry, and they carry TWO facts
142
-
143
- A changed default is invisible in a diff, so it hides. Give it a dedicated item (usually `behavior`),
144
- worded **"was X, now Y, restore via Z"** with the literal restore snippet in the `restore` field —
145
- `null` there when there is genuinely no way back, never an absent field. Do NOT bury it inside a
146
- rename entry. (E.g. a button size default moving `l`→`md`, or a hue default moving to a new palette
147
- family with "point the channel back at `--primary-h/s/l` to keep the old look".)
148
-
149
- **The second fact is what the flip made REDUNDANT, and it belongs in `deleteList`, not in the note.**
150
- A default that moves to what half the consumers were already writing turns their binding into a
151
- restatement — `[reserveMessage]="false"` against a default of `false`, `sortMode="server"` against a
152
- default of `'server'`. 0.7.1 put that sentence in the note and three dead bindings survived the
153
- upgrade; the delete entry is what a finder can run. The linter flags a default-change note with no
154
- `restore`, and a `deleteList` you can write and did not is the failure it cannot see — so write it.
155
-
156
- ## A `deleteList` entry is a find, a why, and a replacement
157
-
158
- `{ id, surface, find, why, replaceWith }`. The whole value is in `find`: the shape in the CONSUMER's
159
- code, written the way they wrote it, a string or an array of them (`["ds-table tr:hover",
160
- "::ng-deep ds-table"]`). `why` says what made it unnecessary — a hook that already existed, a default
161
- that moved, an API that became public. `replaceWith` names the API that replaces it, or the literal
162
- word "nothing" where the answer is simply to delete.
163
-
164
- Two things to get right, both learned from the 45 prose entries that nothing acted on:
165
-
166
- - **Never a bare token as the `find`.** `--ds-menu-item-radius` is OUR name for the fix; their code
167
- says `ds-menu-divider { padding: 0 }`. Grep-ability decides whether the entry exists in practice.
168
- - **Say when the workaround is still legitimate.** `[reserveMessage]="false"` is dead under the new
169
- default and load-bearing under a `dsReserveMessages` host — the entry that omits that turns a
170
- cleanup into a regression.
171
-
172
- ## Changes that aren't a clean find/replace
173
-
174
- - **One-old-maps-to-many-new** (a semantic rename where the replacement depends on context): classify
175
- `behavior`, and in `note` give the **decision rule the agent should follow**, not "review your
176
- usage". Point it at the version's real sources for the exact new name
177
- (`-fg` → resolve to `-text-color` / `-label-color` / `-icon-color` by reading the component's SCSS).
178
- - **Genuinely un-mechanizable residue** stays a `behavior` item with a precise `note`; the workflow
179
- attempts it and escalates to manual review only if it can't be verified — and that escalation is
180
- greppable (the old `old` still present), never silent.
181
-
182
- ## Kind selection (quick map)
183
-
184
- | The change is… | kind |
185
- |---|---|
186
- | identifier → identifier (selector/type/input/output/token/class) | the matching `*-rename` |
187
- | same attribute, values change | `value-remap` (+ `map`) |
188
- | Sass `@use` path / mixin / function moved | `scss-api` |
189
- | new code the consumer must ADD | `code-add` (snippet in `new`, site in `note`, `searchHints` locate it) |
190
- | API removed WITH a replacement path | `removed-api` |
191
- | needs a code edit but not a find/replace (wrap, restructure, changed default/timing/event payload) | `behavior` |
192
- | type of an existing exported member widened or changed | `behavior` (see the widening rule below) |
193
- | documented but needs NO consumer code edit (additive / visual-only / internal) | NOT an item → `informational` |
194
-
195
- **Catch-all:** if you can't confidently fit a breaking/changed entry to a mechanical kind, make it
196
- `behavior` (never drop it). Reading the changelog completely matters more than perfect kinds.
197
-
198
- **One rename can need TWO items.** When an input, a `variant` value or a tone also changes the class
199
- the component puts in the DOM, the `input-rename` / `value-remap` fixes the consumer's *binding* and
200
- finds nothing in their stylesheet — a selector like `.modal.danger` survives the upgrade and silently
201
- matches nothing. Emit a `class-rename` alongside it, element-scoped (`ds-modal .danger`), and say in
202
- the `note` that only consumer STYLING of the internal class is affected. This is how 0.5.1's
203
- `danger` → `error` vocabulary rename left a consumer with a dead destructive-modal stripe: every
204
- binding item was present and correct, the class items were missing (added retroactively 2026-08-03).
205
-
206
- ## actionable vs informational
207
-
208
- Decide by CONTENT, not by which `###` section it sits in — an actionable change can hide in
209
- Added/Changed/Fixed prose, and an "additive" bullet can carry a behavioral default change.
210
- Actionable = existing consumer code stops working or *behaving as before*. Everything else (new
211
- components, new optional inputs, additive tokens whose defaults equal the old role token, pure
212
- bugfixes, visual polish) → `informational`, so a reader knows silence = safe.
213
-
214
- **Members added to an exported class are actionable even when the feature is additive.** Subclassing
215
- a DS component is unsupported (`design-system.md` § Components), but a consumer who does it breaks on
216
- a name collision — TS4114 demands `override`, TS2416 fires when the signature differs — so a release
217
- that only ADDS can fail their build. Emit ONE `behavior` item per release naming the classes whose
218
- member surface grew, with the added member names where few enough to list and the count where not,
219
- `searchHints` that locate the subclass (`extends TableComponent`, `extends `), and a `note` giving the
220
- resolution: rename the subclass's own member, or add `override` where the base's semantics genuinely
221
- match. Keep the feature bullets themselves in `informational` — the item is the collision, not the
222
- feature.
223
-
224
- **Widening an exported type is actionable, and it will not look it.** A field on an exported
225
- interface going `number` → `number | 'content'`, an input going `boolean` → `boolean | null`, a
226
- returned union growing a member — each is source-compatible for whoever WRITES the value and
227
- breaking for whoever READS it back (`sum += col.width` → TS2365) or overrides it in a subclass
228
- (the `equal` position of `InputSignalWithTransform` is invariant, so TS2416 fires even when the
229
- values are compatible). That asymmetry is exactly why release notes describe a widening as a new
230
- capability: 0.10.0 shipped two of these with nothing actionable in the manifest, and the
231
- consumer's type-checker was the only finder — firing only after the bump was already installed.
232
- Emit a `behavior` entry per widened type naming who breaks (readers and overriders — not the
233
- writers, who are fine), with the resolution in the `note`: usually "handle the new union member
234
- where the field is read back", with the literal old → new type.
235
-
236
- **Do not compile either list by eye — run `npm run class-surface`.** It diffs the exported surface
237
- between the last tag and HEAD (`[base] [head]` overrides both ends) and prints it per class:
238
- gained/lost member names AND changed types — annotated fields, `input`/`model`/`output`
239
- initializers, exported interface members, type aliases and `extends` clauses. Twice the names list
240
- was assembled by reading the diff and twice it was wrong in a way a consumer found first (0.8.0's
241
- private `saveLayout`, 0.9.0's sixteen grown classes); the type diff exists because 0.10.0 then
242
- shipped two widenings the same way. What it still cannot see, so check by hand: a member whose
243
- BEHAVIOR changed under an unchanged signature (`TableComponent.isStriped()` went window-relative
244
- to absolute), and a CLASS member that moved to a base class (interface members that move get a
245
- "check the base" hint).
246
-
247
- ## Per-entry checklist
248
-
249
- Run `npm run migration-lint` before you call the manifest done — it mechanises the lines marked
250
- (lint) below, and a release cannot be cut past it. The rest are judgment the linter cannot make.
251
-
252
- - [ ] `id` is a stable, unique kebab slug. (lint)
253
- - [ ] `old`/`new`/`searchHints` are exact code strings; element-scoped as `element[attr]` where shared.
254
- - [ ] `kind` correct; `map` present iff `value-remap`; `new: null` for `behavior`. (lint)
255
- - [ ] `surface` says which of the consumer's artifacts changes — `none` where nothing does. (lint)
256
- - [ ] `detect` carries the consumer's own shapes wherever the affected code names no DS symbol; an
257
- item whose every locator is a DS name while its surface is not the template fails the lint.
258
- - [ ] `verify` states the positive assertion for every `behavior` / `removed-api` entry — what a
259
- recheck can test when there is no old symbol to find. (lint)
260
- - [ ] `value-remap` map: full-token replacements, only changed values listed, identities map to self.
261
- - [ ] Pattern/prefix items state coverage AND exclusions in `note`.
262
- - [ ] Default-value / timing / event-payload changes are their own `behavior` entry, with `restore`
263
- (or an explicit `null`) AND a `deleteList` entry for whatever the flip made redundant. (lint,
264
- for the `restore` half)
265
- - [ ] An entry that reverses an earlier release's guidance links it both ways — `supersedes` here,
266
- `supersededBy` there. (lint, for the references resolving)
267
- - [ ] Substring-colliding renames: longer has its own entry; shorter's `note` says "rename longer first".
268
- - [ ] Non-mechanical entries carry the decision rule + where to read the real new name, not "review".
269
- - [ ] Widened/changed exported types each have a `behavior` entry naming who breaks
270
- (run `npm run class-surface` — do not assemble the list by eye).
271
- - [ ] `deleteList` holds every "you can now delete X" — with a greppable `find`, not our token name,
272
- and a word on when the workaround is still legitimate. (lint, for the shape)
273
- - [ ] Nothing documented in the block is silently dropped (actionable → item; else → `informational`).