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

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.6.0`; prefer the [exact-version Porsche Design System Storefront](https://designsystem.porsche.com/v4.6.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-rc.0`; prefer the [exact-version Porsche Design System Storefront](https://designsystem.porsche.com/v4.7.0-rc.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.6.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-rc.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/AiDropShadow.ts

@@ -0,0 +1,33 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <style>
+        .custom-ai-shadow {
+  --p-button-bg: #fff;
+  --p-button-fg: #000;
+  box-shadow: var(--p-shadow-lg);
+}
+
+.custom-ai-shadow:not(:disabled, :state(loading)):hover {
+  --p-button-bg: var(--p-color-frosted-strong);
+  --p-button-fg: var(--p-color-primary);
+}
+      </style>
+
+      <div class="flex flex-wrap gap-static-lg items-start">
+        <p-button class="custom-ai-shadow" icon="ai-chat" [hideLabel]="true">
+          Ask AI assistant
+        </p-button>
+        <p-button class="custom-ai-shadow" icon="ai-chat">
+          Ask AI assistant
+        </p-button>
+      </div>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

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

@@ -0,0 +1,93 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <style>
+        .custom-ai-orb {
+  --p-button-bg: var(--p-color-canvas);
+  --p-button-fg: var(--p-color-primary);
+  position: relative;
+  z-index: 0;
+}
+
+.custom-ai-orb:not(:disabled, :state(loading)):hover {
+  --p-button-bg: var(--p-color-frosted-strong);
+  --p-button-fg: #fff;
+}
+
+.custom-ai-orb::before,
+.custom-ai-orb::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  z-index: -1;
+  border-radius: inherit;
+  background: linear-gradient(45deg, #00a8ff, #0151e1, #2ae3ff, #bff0ff, #0151e1, #00a8ff);
+  background-size: 400%;
+  animation: custom-ai-orb-gradient 20s linear infinite;
+}
+
+.custom-ai-orb::after {
+  filter: blur(10px);
+  animation:
+    custom-ai-orb-gradient 20s linear infinite,
+    custom-ai-orb-float 8s ease-in-out infinite;
+}
+
+@keyframes custom-ai-orb-gradient {
+  0% {
+    background-position: 0 0;
+  }
+  50% {
+    background-position: 300% 0;
+  }
+  100% {
+    background-position: 0 0;
+  }
+}
+
+@keyframes custom-ai-orb-float {
+  0% {
+    transform: scale(1) rotate(0deg);
+  }
+  50% {
+    transform: scale(1.02) rotate(0.5deg);
+  }
+  100% {
+    transform: scale(1) rotate(0deg);
+  }
+}
+
+/* Respect the user's motion preference */
+@media (prefers-reduced-motion: reduce) {
+  .custom-ai-orb::before,
+  .custom-ai-orb::after {
+    animation: none;
+  }
+}
+
+/* Decorative gradient is not conveyed in forced-colors mode */
+@media (forced-colors: active) {
+  .custom-ai-orb::before,
+  .custom-ai-orb::after {
+    display: none;
+  }
+}
+      </style>
+
+      <div class="flex flex-wrap gap-static-lg items-start">
+        <p-button class="custom-ai-orb" icon="ai-chat" [hideLabel]="true">
+          Ask AI assistant
+        </p-button>
+        <p-button class="custom-ai-orb" icon="ai-chat">
+          Ask AI assistant
+        </p-button>
+      </div>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}