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

package/skill/references/components/p-heading/p-heading.md

@@ -0,0 +1,78 @@
+# p-heading
+
+`p-heading` is used to highlight and specify heading styling and hierarchy in documents.
+
+> **Recommendation**
+>
+> Although the component is very sophisticated, it's recommended (if possible) to use the corresponding utility classes of the "@porsche-design-system/components-{js | angular | react | vue}/tailwindcss" sub-package or any of the other styling solutions for best performance since way less DOM nodes are required to render. Further information can be found [here](../../styles/tailwindcss.md).
+
+## Usage
+
+p-heading is used to highlight and specify heading styling and hierarchy
+
+### Do:
+
+- Use p-heading styles to clearly mark section titles and subsections.
+- Align headings with the grid to maintain visual rhythm.
+- Use heading-xx-large for primary sections; scale down for subsections.
+- Pair each heading with a text style one or two steps smaller (e.g. heading-large with text-medium).
+
+### Don't:
+
+- Don’t use p-heading styles for hero or marketing intros—use p-display instead.
+- Don’t mix heading sizes inconsistently within the same view.
+- Don’t center-align headings in content-heavy layouts unless intended for a special moment.
+
+## Accessibility support
+
+This component does not include any special accessibility features.
+
+## Development considerations
+
+### Heading hierarchy
+
+While using the `Heading` component, take care of the correct heading hierarchy which can be adjusted through the `tag` property. Keep in mind that the visual appearance must not always be identical with the semantic hierarchy.
+
+#### Best practices
+
+- Use one unique `h1` per page that describes what that page is about.
+- Use headings to describe the content below. Do not use an HTML heading just to make the text appear bigger or stand out.
+- Use heading levels like the index of a book: hierarchical.
+- Do not choose a heading by its size, but by its level in the context of the content.
+- Heading hierarchy should not increase by more than one level at a time.
+- Do not skip a heading level from the top down.
+
+### Common do's and don'ts
+
+- **Do** use the `tag` prop to reflect the semantic hierarchy, not just visual size.
+- **Do** keep one unique `h1` per page.
+- **Don't** choose a heading level based on appearance alone.
+- **Don't** skip heading levels when nesting sections.
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `align` | `'start'` `'center'` `'end'` `'inherit'` | `'start'` | Sets the horizontal text alignment (`start`, `center`, `end`, or `inherit`). |
+| `color` | `'primary'` `'contrast-higher'` `'contrast-high'` `'contrast-medium'` `'inherit'` | `'primary'` | Sets the text color using PDS color tokens. |
+| `ellipsis` | `boolean` | `false` | Truncates the text with an ellipsis when it overflows the container on a single line. Cannot be combined with multi-line content. |
+| `hyphens` | `'none'` `'manual'` `'auto'` `'inherit'` | `'none'` | Controls hyphenation behavior — `auto` lets the browser decide, `manual` only breaks at `­`, `none` disables it entirely. |
+| `size` | `'2xs'` `'xs'` `'sm'` `'md'` `'lg'` `'xl'` `'2xl'` `'3xl'` `'4xl'` `'5xl'` `'inherit'`<br>_deprecated:_ `'small'` `'medium'` `'large'` `'x-large'` `'xx-large'`<br>`BreakpointCustomizable<HeadingSize>` | `'2xl'` | Sets the visual size of the heading. Use `inherit` to derive size from the parent. Supports responsive breakpoint values. |
+| `tag` | `undefined` `'h1'` `'h2'` `'h3'` `'h4'` `'h5'` `'h6'` | `undefined` | Sets the HTML heading tag (h1–h6) for correct document outline placement. When omitted, the tag is inferred from `size`. |
+| `weight` | `'normal'` `'semibold'` `'bold'`<br>_deprecated:_ `'regular'` `'semi-bold'` | `'normal'` | Sets the font weight — `normal`, `semibold`, or `bold`. |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| _(default)_ | no | — | Default slot to render the heading. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.ts](./examples/Default.ts) |
+| Semantics | To provide more contextual HTML semantics you can either pass them with the `tag` property or directly inside a slot. | [./examples/Semantics.ts](./examples/Semantics.ts) |
+| Color | Predefined theme-based colors are available, but `inherit` can also be used to define a custom color. | [./examples/Color.ts](./examples/Color.ts) |

package/skill/references/components/p-icon/examples/Color.ts

@@ -0,0 +1,16 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-text [style]="{'color': 'light-dark(mediumvioletred, deeppink)'}" color="inherit">
+        <p-icon class="me-static-sm" color="inherit" name="highway" [aria]="{'aria-label': 'Highway icon'}"></p-icon>
+        Some text
+      </p-text>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-icon/examples/ColorCssVar.ts

@@ -0,0 +1,13 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-icon class="[--p-icon-color:deeppink]" name="highway" [aria]="{'aria-label': 'Highway icon'}"></p-icon>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-icon/examples/Custom.ts

@@ -0,0 +1,13 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-icon source="assets/icon-custom-kaixin.svg" [aria]="{'aria-label': 'Icon for social media platform Kaixin'}"></p-icon>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}

package/skill/references/components/p-icon/examples/Default.ts

@@ -0,0 +1,13 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { PorscheDesignSystemModule } from '@porsche-design-system/components-angular';
+
+@Component({
+  selector: 'porsche-design-system-app',
+  template: `
+      <p-icon></p-icon>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true,
+  imports: [PorscheDesignSystemModule], // <-- PDS module is imported here
+})
+export class ExampleComponent {}