@porsche-design-system/components-angular 4.7.0-beta.0 → 4.7.0

package/skills/pds-audit-deprecations-angular/references/report-template.md

@@ -0,0 +1,128 @@
+# Markdown report template
+
+The Markdown report is a rendering of the validated JSON, written to the structure below. It is the file a human opens and the file an agent is later asked to act on, so its shape is fixed rather than composed per run: the same sections, in the same order, every time.
+
+## How to read this template
+
+- Reproduce every section, in this order, with these headings verbatim. Add none, drop none.
+- `<…>` is a placeholder naming the JSON path it renders, so every line of the report is traceable to the field it came from. One ending in `[]` is a repeated item: render one entry per array element.
+- A line marked `— only when …` is rendered only in that case and omitted entirely otherwise. The marker itself is never written into the report.
+- Empty-state sentences are given verbatim. Write the sentence rather than dropping the section, so an empty section never reads as a missing one.
+- Compute every count from the arrays you validated. Never write one from memory: a number that disagrees with the list under it discredits the whole report.
+- Nothing enters the report that is not in the JSON. Anything else worth saying — that `.pds/` is not git-ignored, for instance — belongs in your reply to the user, not in this file.
+
+## Template
+
+````markdown
+# Porsche Design System deprecation audit (angular) — <audit.runId>
+
+- **PDS version audited:** `<audit.pdsVersion>`
+- **Framework:** `angular`
+- **Project root:** `<project.root>`
+- **Packages:** `<project.pdsPackages[].name>@<project.pdsPackages[].version>` — one per entry, comma-separated
+- **Generated at:** <audit.generatedAt>
+- **Result:** `<summary.result>`
+
+## Scope
+
+### Included
+
+- `<scope.includedPaths[]>`
+
+### Excluded
+
+- `<scope.excludedPaths[].path>` — <scope.excludedPaths[].reason>
+
+Nothing was excluded. — only when `scope.excludedPaths` is empty, replacing the list
+
+## Coverage
+
+### Skipped files
+
+- `<coverage.skippedFiles[].path>` — <coverage.skippedFiles[].reason>
+
+No eligible files were skipped. — only when `coverage.skippedFiles` is empty, replacing the list
+
+### Limitations
+
+- <coverage.limitations[]>
+
+No limitations to report. — only when `coverage.limitations` is empty, replacing the list
+
+## Summary
+
+- **<number of findings>** findings across **<number of evidence locations across all findings>** locations
+- **<number of manual follow-ups>** manual follow-ups
+
+| Effort | Findings |
+| --- | --- |
+| `<effort>` | <number of findings with that effective effort> |
+
+| Confidence | Findings |
+| --- | --- |
+| `<confidence>` | <number of findings with that confidence> |
+
+## Findings
+
+Ordered cheapest first — effective effort ascending, then confidence, then occurrence count descending, then rule id. This order is the recommended action plan.
+
+### <position in `findings`>. <findings[].title>
+
+- **Rule id:** `<findings[].ruleId>`
+- **Kind:** `<findings[].usageKind>`
+- **Confidence:** `<findings[].confidence>`
+- **Effort:** `<findings[].baselineEffort>` (baseline)
+- **Effort:** `<findings[].observedEffort>` (observed — baseline `<findings[].baselineEffort>`) — only when `observedEffort` is present, replacing the line above
+- **Effort rationale:** <findings[].effortRationale> — only when `observedEffort` is present
+- **Deprecation message:** <findings[].deprecationMessage> — only when present
+- **Replacement:** `<findings[].remediation.replacement.from>` → `<findings[].remediation.replacement.to>` — only when present
+- **Instruction:** <findings[].remediation.instruction>
+- **Sources:**
+  - `pds-knowledge-angular/<findings[].sources[].reference>` (PDS <findings[].sources[].pdsVersion>)
+- **Locations (<number of entries in `findings[].evidence`>):**
+  - `<findings[].evidence[].path>:<findings[].evidence[].line>` — `<findings[].evidence[].detection>`, value `<findings[].evidence[].valueResolution>` — the value half only when `valueResolution` is present
+    ```
+    <findings[].evidence[].snippet>
+    ```
+    anchored by `<findings[].evidence[].anchor.path>:<findings[].evidence[].anchor.line>` — only when `anchor` is present, together with the block below
+    ```
+    <findings[].evidence[].anchor.snippet>
+    ```
+
+No deprecated usage was found. — only when `findings` is empty, replacing the ordering sentence, the entries and both Summary tables
+
+## Manual follow-ups
+
+Detected but not statically resolvable. These are for a human to review — do not fix them automatically.
+
+### <position in `manualFollowUps`>. <manualFollowUps[].subject>
+
+- **Rule id:** `<manualFollowUps[].ruleId>` — only when present
+- **Reason:** <manualFollowUps[].reason>
+- **Evidence (<number of entries in `manualFollowUps[].evidence`>):**
+  - `<manualFollowUps[].evidence[].path>:<manualFollowUps[].evidence[].line>`
+    ```
+    <manualFollowUps[].evidence[].snippet>
+    ```
+
+No manual follow-ups. — only when `manualFollowUps` is empty, replacing the entries
+
+## How to act on this report
+
+This report describes Porsche Design System `<audit.pdsVersion>` and is only valid for that version. After upgrading the package, run the audit again rather than working from this file.
+
+Findings are ordered cheapest first, so the list is the action plan: work down it. Applying one takes two lookups against `pds-knowledge-angular`, and neither is optional. Re-check the rule id against the deprecation index: it is the only thing that establishes an API is still deprecated and what replaces it, and it describes the installed version rather than the one this report was written against. Then open the reference the finding lists under **Sources**, which documents how the replacement is actually written — **Instruction** and **Replacement** name the edit, not the current API.
+
+Manual follow-ups are for a human to resolve and must not be fixed automatically. Their values could not be determined statically, so it is not established that they are deprecated at all.
+
+Re-run this audit over the same scope afterwards. A clean re-run is the only reliable confirmation that a finding has been resolved.
+````
+
+## The values the template derives
+
+Four things above are computed rather than copied, and each has exactly one right answer:
+
+- **Effective effort** is `observedEffort` when present, else `baselineEffort`. It is what the findings order and the Summary effort table both use.
+- **Breakdown rows** list only buckets that have findings, ordered `trivial`, `small`, `medium`, `large` and `high`, `medium` — the same direction as the findings themselves, so the cheapest and most certain work reads first.
+- **Finding numbers** are the position in `findings`, so `### 1.` is the first thing to fix. Manual follow-ups are numbered the same way.
+- **Source paths** are skill-qualified: `pds-knowledge-angular` followed by the stored `reference`, which is relative to that skill's root. They point at the reference documenting the replacement, never at the deprecation index.

package/skills/pds-audit-deprecations-angular/references/report.schema.json

@@ -0,0 +1,446 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://designsystem.porsche.com/schemas/pds-audit-deprecations-angular/1.0.0.json",
+  "title": "Porsche Design System deprecation audit report (angular)",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "audit",
+    "project",
+    "scope",
+    "summary",
+    "coverage",
+    "findings",
+    "manualFollowUps"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "1.0.0"
+    },
+    "audit": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "runId",
+        "generatedAt",
+        "skillName",
+        "auditKind",
+        "framework",
+        "pdsVersion"
+      ],
+      "properties": {
+        "runId": {
+          "type": "string",
+          "description": "Filesystem-safe UTC timestamp identifying the run, e.g. 2026-07-23T09-21-27Z."
+        },
+        "generatedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "skillName": {
+          "const": "pds-audit-deprecations-angular"
+        },
+        "auditKind": {
+          "const": "deprecations",
+          "description": "What this report audits, for a consumer reading a run directory of several."
+        },
+        "framework": {
+          "const": "angular"
+        },
+        "pdsVersion": {
+          "type": "string",
+          "description": "The installed PDS version the audit was run against."
+        }
+      }
+    },
+    "project": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "root",
+        "pdsPackages"
+      ],
+      "properties": {
+        "root": {
+          "type": "string"
+        },
+        "pdsPackages": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "name",
+              "version"
+            ],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "version": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "includedPaths",
+        "excludedPaths"
+      ],
+      "description": "What the run covered, as a list rather than as a claim about the file walk. A package that was never discovered is a package nobody can see was missed, so `completed` is checked against these two arrays.",
+      "properties": {
+        "includedPaths": {
+          "type": "array",
+          "description": "Every path the run audited, project-relative: one entry per discovered PDS-dependent package root, narrowed by any user-supplied include paths. `.` when the project is a single package.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "excludedPaths": {
+          "type": "array",
+          "description": "Every path deliberately left out, each with why — user-supplied excludes, default exclusions such as tests or build output, and any discovered package the run chose not to audit. A choice belongs here and not in `coverage.limitations`, which is for what the audit could not do.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "path",
+              "reason"
+            ],
+            "properties": {
+              "path": {
+                "type": "string"
+              },
+              "reason": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "result"
+      ],
+      "description": "Execution state and nothing else. Counts are deliberately absent: each one would be the length of an array in this same file, and a written number is a number that can disagree with the list beside it.",
+      "properties": {
+        "result": {
+          "enum": [
+            "completed",
+            "partial",
+            "failed"
+          ],
+          "description": "Execution state only, never project quality: completed = every discovered PDS-dependent package audited and every eligible file in it checked; partial = a discovered package went unaudited or something eligible could not be checked; failed = no meaningful audit was possible."
+        }
+      }
+    },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "skippedFiles",
+        "limitations"
+      ],
+      "description": "Deliberately thin. Anything here is the audit grading its own work, which no consumer can check, so it carries only what a reader can act on: paths they can open, and gaps stated in words. Without it a `partial` result names no gap at all.",
+      "properties": {
+        "skippedFiles": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "path",
+              "reason"
+            ],
+            "properties": {
+              "path": {
+                "type": "string"
+              },
+              "reason": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "limitations": {
+          "type": "array",
+          "description": "Anything that prevented a complete check, disclosed in full. Only what the audit could not do — anything it chose to leave out is a decision and belongs in `scope.excludedPaths` with its reason.",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "description": "Every deprecated usage found, ordered cheapest first: effective effort ascending, then confidence, then occurrence count descending, then ruleId. That order is the recommended action plan.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "ruleId",
+          "usageKind",
+          "title",
+          "confidence",
+          "baselineEffort",
+          "remediation",
+          "evidence",
+          "sources"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Run-unique finding id."
+          },
+          "ruleId": {
+            "type": "string",
+            "description": "The deprecation index entry id, e.g. prop/p-accordion/heading, copied verbatim. Stable across releases, so findings stay comparable between runs."
+          },
+          "usageKind": {
+            "enum": [
+              "component",
+              "prop",
+              "propValue",
+              "event",
+              "slot",
+              "cssCustomProperty",
+              "cssClass",
+              "scssVariable",
+              "scssMixin",
+              "jsExport"
+            ],
+            "description": "The rule id's first segment."
+          },
+          "title": {
+            "type": "string",
+            "description": "One line naming the deprecated API, e.g. \"Deprecated prop heading on p-accordion\"."
+          },
+          "deprecationMessage": {
+            "type": "string",
+            "description": "The index entry’s message, carried verbatim when it has one."
+          },
+          "confidence": {
+            "enum": [
+              "high",
+              "medium"
+            ],
+            "description": "Derived, not judged: the lowest confidence across this finding’s evidence locations."
+          },
+          "baselineEffort": {
+            "enum": [
+              "trivial",
+              "small",
+              "medium",
+              "large"
+            ],
+            "description": "Derived from usageKind, one level higher when the index documents no replacement."
+          },
+          "observedEffort": {
+            "enum": [
+              "trivial",
+              "small",
+              "medium",
+              "large"
+            ],
+            "description": "Only when this project implements the API in a way that changes the real cost."
+          },
+          "effortRationale": {
+            "type": "string",
+            "description": "Required whenever observedEffort is present, and must point at evidence already listed on this finding — otherwise the deviation is unreviewable."
+          },
+          "remediation": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "instruction"
+            ],
+            "properties": {
+              "replacement": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "from",
+                  "to"
+                ],
+                "description": "The exact edit, in this framework’s spelling. Present only when the index documents an unambiguous replacement, so a fix never has to re-derive it from prose.",
+                "properties": {
+                  "from": {
+                    "type": "string"
+                  },
+                  "to": {
+                    "type": "string"
+                  }
+                }
+              },
+              "instruction": {
+                "type": "string",
+                "description": "What to do, in words. When no replacement is documented, say so plainly rather than inventing one."
+              }
+            }
+          },
+          "evidence": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "path",
+                "line",
+                "snippet",
+                "detection"
+              ],
+              "properties": {
+                "path": {
+                  "type": "string",
+                  "description": "Project-relative path."
+                },
+                "line": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "The usage itself — the attribute, tag, property or alias reference. Never the import, @use, @theme or declaration line that anchored or resolved it: those belong in `anchor`, and counting them as locations makes two runs of the same project disagree on how many there are."
+                },
+                "snippet": {
+                  "type": "string",
+                  "description": "The source line, quoted verbatim."
+                },
+                "detection": {
+                  "enum": [
+                    "direct",
+                    "wrapper-forwarded",
+                    "wrapper-transformed",
+                    "fallback-search"
+                  ],
+                  "description": "How this location was reached. Determines its confidence."
+                },
+                "valueResolution": {
+                  "enum": [
+                    "literal",
+                    "same-file-constant",
+                    "imported-constant"
+                  ],
+                  "description": "How the deprecated value was resolved. Only for usageKind `propValue`."
+                },
+                "anchor": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "path",
+                    "line",
+                    "snippet"
+                  ],
+                  "properties": {
+                    "path": {
+                      "type": "string",
+                      "description": "Project-relative path."
+                    },
+                    "line": {
+                      "type": "integer",
+                      "minimum": 1,
+                      "description": "The anchoring line, which is frequently in a different file from the usage."
+                    },
+                    "snippet": {
+                      "type": "string",
+                      "description": "The source line, quoted verbatim."
+                    }
+                  },
+                  "description": "The line that proves this usage is PDS — the import, the resolved SCSS @use including one injected by build config, the Tailwind @theme import, or the PDS root at the far end of a wrapper chain. The only truthful home for the vite.config.ts line that anchors a stylesheet naming PDS nowhere. Omitted only when the usage anchors itself, as a --p- custom property does."
+                }
+              }
+            }
+          },
+          "sources": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Where the fact came from, so a reader or a fix skill can re-ground the finding.",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "reference",
+                "pdsVersion"
+              ],
+              "properties": {
+                "reference": {
+                  "type": "string",
+                  "description": "Knowledge-skill reference the fact comes from, as a path relative to that skill’s root — the same form the knowledge skill uses for its own links, so a consumer can resolve it without guessing the base directory."
+                },
+                "pdsVersion": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "dependentRequired": {
+          "observedEffort": [
+            "effortRationale"
+          ]
+        }
+      }
+    },
+    "manualFollowUps": {
+      "type": "array",
+      "description": "Deprecated usage that was detected but could not be resolved. Kept apart from findings because a follow-up has no fix to apply — anything acting on this report leaves these to a human.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "subject",
+          "reason",
+          "evidence"
+        ],
+        "properties": {
+          "subject": {
+            "type": "string",
+            "description": "What could not be resolved, e.g. \"p-text size\". Free text, since a follow-up often spans several index entries."
+          },
+          "ruleId": {
+            "type": "string",
+            "description": "Only when the follow-up maps to exactly one index entry, and then copied verbatim. Omit it rather than inventing one: an id that is not in the index cannot be looked up or compared across runs."
+          },
+          "reason": {
+            "type": "string",
+            "description": "Why it could not become a finding — dynamic value, unanchored match, spread props."
+          },
+          "evidence": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "path",
+                "line",
+                "snippet"
+              ],
+              "properties": {
+                "path": {
+                  "type": "string",
+                  "description": "Project-relative path."
+                },
+                "line": {
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "snippet": {
+                  "type": "string",
+                  "description": "The source line, quoted verbatim."
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/skills/pds-knowledge-angular/SKILL.md

@@ -13,13 +13,13 @@ Prefer Porsche Design System components and tokens for new UI, even when the use
 
 ## Coverage and fallbacks
 
-This skill currently covers components, global stylesheets and theming, tokens, and styling integrations. It does not yet include complete getting-started, setup, and installation guidance; the v3-to-v4 migration guide; the changelog; partials; patterns and templates; the AG Grid theme; or the Storefront’s Must Know and Help sections.
+This skill currently covers components, global stylesheets and theming, tokens, styling integrations, and the deprecated API index. It does not yet include complete getting-started, setup, and installation guidance; the v3-to-v4 migration guide; the changelog; partials; patterns and templates; the AG Grid theme; or the Storefront’s Must Know and Help sections.
 
-Before using documentation outside this skill or the installed package, match it to the installed PDS version. This skill was generated for `4.7.0-beta.0`; prefer the [exact-version Porsche Design System Storefront](https://designsystem.porsche.com/v4.7.0-beta.0/). Major-version URLs such as `/v4/` always serve the latest v4 release and may describe APIs or setup introduced after the installed version. Use them only as a fallback and verify relevant details against the installed package.
+Before using documentation outside this skill or the installed package, match it to the installed PDS version. This skill was generated for `4.7.0`; prefer the [exact-version Porsche Design System Storefront](https://designsystem.porsche.com/v4.7.0/). Major-version URLs such as `/v4/` always serve the latest v4 release and may describe APIs or setup introduced after the installed version. Use them only as a fallback and verify relevant details against the installed package.
 
 For runnable patterns and templates, consult the [Porsche Design System examples repository](https://github.com/porsche-design-system/examples), selecting a release tag or commit that matches the installed package instead of assuming its default branch is compatible. For release-specific changes, read `../../CHANGELOG.md`.
 
-For exact API facts, inspect the installed typings and metadata first. When readable implementation details are necessary, use the [exact-version component source](https://github.com/porsche-design-system/porsche-design-system/tree/v4.7.0-beta.0/packages/components/src/components) under the repository's `packages/components/src/components/<component>` directory. Do not use the default branch, which may represent a newer release.
+For exact API facts, inspect the installed typings and metadata first. When readable implementation details are necessary, use the [exact-version component source](https://github.com/porsche-design-system/porsche-design-system/tree/v4.7.0/packages/components/src/components) under the repository's `packages/components/src/components/<component>` directory. Do not use the default branch, which may represent a newer release.
 
 For deployed browser behavior, inspect component requests in the Network panel. Treat these minified, content-hashed CDN artifacts as a debugging fallback; use the exact-version repository source for readable implementation details.
 
@@ -122,3 +122,9 @@ Note: the code examples in the component references use PDS Tailwind utility cla
 | SCSS | Sass variables and mixins under the `pds` namespace | [scss.md](references/styles/scss.md) |
 | vanilla-extract | typed tokens and utilities in `*.css.ts` files | [vanilla-extract.md](references/styles/vanilla-extract.md) |
 | Emotion | tokens and utilities in `css`/`styled` styles | [emotion.md](references/styles/emotion.md) |
+
+## Deprecations
+
+Every deprecated API in this version is indexed in [deprecations.md](references/deprecations.md) — components, props, prop values, events, slots, CSS variables and the styling packages’ deprecated aliases, with what to use instead.
+
+Read it when checking existing code, when a prop or value looks unfamiliar, or before assuming an API is current. It is indexed by what is deprecated, so one read covers the whole surface; the component and styling references cover the same facts per component. Never introduce a deprecated API in new code.

package/skills/pds-knowledge-angular/references/components/p-button/examples/AiGradientGlow.ts

@@ -14,7 +14,7 @@ import { PorscheDesignSystemModule } from '@porsche-design-system/components-ang
 
 .custom-ai-orb:not(:disabled, :state(loading)):hover {
   --p-button-bg: var(--p-color-frosted-strong);
-  --p-button-fg: var(--p-color-primary);
+  --p-button-fg: #fff;
 }
 
 .custom-ai-orb::before,