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

package/skill/references/components/p-input-time/p-input-time.md

@@ -0,0 +1,144 @@
+# p-input-time
+
+The `p-input-time` component provides a versatile, user‑friendly interface for entering time values. It supports direct keyboard input, including arrow-key adjustments for precise changes. It has a start and end slot in order to support flexible slotted content.
+
+A `label` is a caption which informs the user what information a particular form field is asking for. The `p-input-time` component can be used with or without a label, but it's recommended to keep the label visible for better accessibility whenever possible. When used without a label, it's mandatory to provide a descriptive label text for screen readers.
+
+While a `placeholder` is optional but recommended to be set whenever bits of example content or hints shall be shown to give the user visual cues to fill out the form.
+
+> **Input Event Handling**
+>
+> React's `onChange` behaves like the native `onInput` (fires on every keystroke). However, our web components follow standard browser behavior, where `onChange` only fires when the input loses focus. To get real-time updates on each keystroke, use `onInput` instead.
+
+## Usage
+
+`p-input-time` is intended for time input scenarios. It should not be used for values that merely happen to consist of digits. For those cases, consider using another input with an appropriate input mode. For further guidance, see the [MDN documentation on time inputs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/time#using_time_inputs).
+
+### Do:
+
+- Use when a time value is required or optional.
+- Use without a label only when the context is clear.
+- Use for validation and error of input.
+- Use asterisk for required fields.
+
+### Don't:
+
+- Don't use labels with more than two words whenever possible (keep it short and descriptive).
+- Don't use instructional or description text for the label.
+
+---
+
+## Related Components
+
+- [Input Date](../p-input-date/p-input-date.md)
+- [Input Email](../p-input-email/p-input-email.md)
+- [Input Month](../p-input-month/p-input-month.md)
+- [Input Number](../p-input-number/p-input-number.md)
+- [Input Password](../p-input-password/p-input-password.md)
+- [Input Search](../p-input-search/p-input-search.md)
+- [Input Tel](../p-input-tel/p-input-tel.md)
+- [Input Text](../p-input-text/p-input-text.md)
+- [Input Url](../p-input-url/p-input-url.md)
+- [Input Week](../p-input-week/p-input-week.md)
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element. |
+| `Arrow Up/Down` | Sets increments/decrements in regards of the steps |
+
+### ARIA enhancements
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-describedby="IDREF"` | Defines the accessible description combined with the status message. |
+| `role="status"`, `role="alert"` | When `message` and `state` or `loading` prop change, the status message is announced. |
+| `aria-hidden="true"` | If `required` attribute is set, the visible asterisk indicator is hidden from assistive technologies. |
+| `aria-invalid="true"` | If `error` state is set. |
+| `aria-live="polite"` | If the `maxlength` attribute is present, the counter is announced via ARIA live region. |
+
+## Development considerations
+
+### Disabled state
+
+In general, avoid using the `disabled` state. Disabled elements are no longer focusable and may be missed by screen reader users. They can also confuse sighted users if the reason they are disabled is not made clear.
+
+### Common do's and don'ts
+
+- **Do** keep a persistent label and use helper/description text when additional context is required.
+- **Do** use the component state/message API so validation and status changes are announced.
+- **Do** use clear error wording that helps users recover.
+- **Don't** rely on placeholder text as the only label.
+- **Don't** use `hide-label` without an accessible name.
+
+## Limitations
+
+Due to the nature of **Web Components** and **shadow DOM**, there are limitations when using some **ARIA** attributes to define relationships between elements across different shadow DOMs or shadow DOM/light DOM combinations.
+
+| ARIA | Support |
+| --- | --- |
+| `aria-labelledby` | 🚫 |
+| `aria-describedby` | 🚫 |
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `autoComplete` | `string` | `undefined` | Provides the browser with a time autofill hint. |
+| `compact` | `boolean` | `false` | Reduces the input height and padding for a more compact layout. |
+| `description` | `string` | `''` | Sets a supplementary description displayed below the label to provide additional context. |
+| `disabled` | `boolean` | `false` | Disables the field, preventing time selection. The value is not submitted with the form. |
+| `form` | `string` | `undefined` | Associates the field with a form element by its ID when the field is not nested directly inside it. |
+| `hideLabel` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values. |
+| `label` | `string` | `''` | Sets the visible label text displayed above the input field. |
+| `loading` _(experimental)_ | `boolean` | `false` | @experimental Disables the field and displays a loading spinner to indicate an ongoing operation. |
+| `max` | `string` | `undefined` | Sets the latest selectable time in `hh:mm` or `hh:mm:ss` format. Times after this are disabled in the picker. |
+| `message` | `string` | `''` | Sets the validation feedback message displayed below the field when `state` is `success` or `error`. |
+| `min` | `string` | `undefined` | Sets the earliest selectable time in `hh:mm` or `hh:mm:ss` format. Times before this are disabled in the picker. |
+| `name` _(required)_ | `string` | `undefined` | Sets the name submitted with the form data to identify this field's value on the server. |
+| `readOnly` | `boolean` | `false` | Makes the field read-only — the value is displayed but cannot be changed. The value is still submitted with the form. |
+| `required` | `boolean` | `false` | Marks the field as required — form submission is blocked while no time is selected. |
+| `state` | `'none'` `'error'` `'success'` | `'none'` | Sets the validation state, controlling the visual appearance and style of the feedback message (`none`, `success`, `error`). |
+| `step` | `number` | `60` | Sets the stepping interval in seconds. Use `60` for minute-level selection, `1` to also expose seconds. |
+| `value` | `string | null` | `''` | Sets the current time value in `hh:mm` or `hh:mm:ss` format (e.g. `14:00`). |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `blur` | `CustomEvent<InputTimeBlurEventDetail>`<br>`Event` | Emitted when the input loses focus, regardless of whether the value changed. |
+| `change` | `CustomEvent<InputTimeChangeEventDetail>`<br>`Event` | Emitted when the input loses focus after its value was changed. |
+| `input` | `CustomEvent<InputTimeInputEventDetail>`<br>`InputEvent` | Emitted on every value change as the user interacts with the time picker. |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| `label` | no | — | Shows a label. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| `label-after` | no | — | Places additional content after the label text (for content that should not be part of the label, e.g. external links or `p-popover`). |
+| `description` | no | — | Shows a description. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| `message` | no | — | Shows a state message. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| `start` | no | — | Shows content at the start of the input (e.g. unit prefix). |
+| `end` | no | — | Shows content at the end of the input (e.g. toggle button, unit suffix). |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--ref-p-input-slotted-padding` | — | When slotting a `p-button-pure` or `p-link-pure` this variable needs to be set as `padding` in oder to adjust the alignment correctly. |
+| `--ref-p-input-slotted-margin` | — | When slotting a `p-button-pure` or `p-link-pure` this variable needs to be set as `margin` in oder to adjust the spacings correctly. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |
+| Form | The `p-input-time` can be integrated into a form in two ways: **controlled** or **uncontrolled**, depending on your needs. | [./examples/Form.tsx](./examples/Form.tsx) |
+| Slots | Use named slots when `label`, `description` or `message` need markup such as a link. | [./examples/Slots.tsx](./examples/Slots.tsx) |

package/skill/references/components/p-input-url/examples/Default.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import { PInputUrl } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PInputUrl label="Some label" name="some-name" indicator={true}></PInputUrl>
+    </>
+  )
+}

package/skill/references/components/p-input-url/examples/Form.tsx

@@ -0,0 +1,45 @@
+import React from 'react';
+import {
+  type InputUrlInputEventDetail,
+  PButton,
+  PInputUrl,
+  type PInputUrlProps,
+  PText,
+} from '@porsche-design-system/components-react';
+import { FormEvent, useState } from 'react';
+
+export const Example = () => {
+  const [form, setForm] = useState({ myInputUrl: '' });
+  const [lastSubmittedData, setLastSubmittedData] = useState<any>();
+
+  const onInput = (e: CustomEvent<InputUrlInputEventDetail>) => {
+    const { name, value } = e.target as HTMLElement & PInputUrlProps;
+    setForm((prev) => ({
+      ...prev,
+      [name]: value,
+    }));
+  };
+
+  const onSubmit = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    setLastSubmittedData(JSON.stringify(form));
+  };
+
+  const onReset = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    setForm({ myInputUrl: '' });
+  };
+
+  return (
+    <>
+      <form onSubmit={onSubmit} onReset={onReset} className="flex flex-col gap-fluid-sm">
+        <PInputUrl name="myInputUrl" label="Some Label" indicator={true} value={form.myInputUrl} onInput={onInput} />
+        <div className="flex gap-fluid-sm">
+          <PButton type="submit">Submit</PButton>
+          <PButton type="reset">Reset</PButton>
+        </div>
+        <PText>Last submitted data: {lastSubmittedData}</PText>
+      </form>
+    </>
+  );
+};

package/skill/references/components/p-input-url/examples/Slots.tsx

@@ -0,0 +1,41 @@
+import React from 'react';
+import { PButtonPure, PIcon, PInputUrl, PPopover } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PInputUrl state="error">
+        <span slot="label">
+          Some label with a 
+          <a href="https://designsystem.porsche.com" className="underline">
+            link
+          </a>
+           and a "label-after" slot.
+        </span>
+        <PPopover slot="label-after">
+          Some Popover content with a 
+          <a href="https://designsystem.porsche.com" className="underline">
+            link
+          </a>
+          .
+        </PPopover>
+        <span slot="description">
+          Some description with a 
+          <a href="https://designsystem.porsche.com" className="underline">
+            link
+          </a>
+          .
+        </span>
+        <PIcon slot="start" name="home" color="contrast-medium" aria-hidden={true}></PIcon>
+        <PButtonPure slot="end" icon="delete" hideLabel={true} className="p-(--ref-p-input-slotted-padding) m-(--ref-p-input-slotted-margin)" aria={{'aria-label': 'Delete'}}></PButtonPure>
+        <span slot="message">
+          Some error message with a 
+          <a href="https://designsystem.porsche.com" className="underline">
+            link
+          </a>
+          .
+        </span>
+      </PInputUrl>
+    </>
+  )
+}

package/skill/references/components/p-input-url/p-input-url.md

@@ -0,0 +1,145 @@
+# p-input-url
+
+The `p-input-url` component provides a user-friendly, accessible interface for entering valid website URLs. It leverages native HTML5 URL validation and ensures appropriate keyboard behavior on mobile devices. It includes `start` and `end` slots to flexibly incorporate icons, buttons, or other elements within the input field.
+
+A `label` tells the user what information a form field is asking for. The `p-input-url` component can be used with or without a label, but it is recommended to keep the label visible whenever possible for better accessibility. When used without a label, a descriptive label text for screen readers is required.
+
+A `placeholder` is optional, but recommended when example content or hints should be shown to give the user visual cues for completing the form.
+
+> **Input Event Handling**
+>
+> React's `onChange` behaves like the native `onInput` (fires on every keystroke). However, our web components follow standard browser behavior, where `onChange` only fires when the input loses focus. To get real-time updates on each keystroke, use `onInput` instead.
+
+## Usage
+
+The `p-input-url` component is specifically designed for collecting website URLs. It leverages built-in browser validation to ensure that the input follows the correct URL format. This makes it a better choice than a generic text input when URL validation, proper keyboard behavior on mobile devices, and accessibility are important. For further guidance, see the [MDN documentation on url inputs](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/url).
+
+### Do:
+
+- Use when requesting a website URL from the user.
+- Use without a label only when the context is clear.
+- Use it when URL validation and clear input errors are needed.
+- Use an asterisk for required fields.
+
+### Don't:
+
+- Don't use labels with more than two words whenever possible (keep it short and descriptive).
+- Don't use an instructional or description text for the label.
+
+---
+
+## Related Components
+
+- [Input Date](../p-input-date/p-input-date.md)
+- [Input Email](../p-input-email/p-input-email.md)
+- [Input Month](../p-input-month/p-input-month.md)
+- [Input Number](../p-input-number/p-input-number.md)
+- [Input Password](../p-input-password/p-input-password.md)
+- [Input Search](../p-input-search/p-input-search.md)
+- [Input Tel](../p-input-tel/p-input-tel.md)
+- [Input Text](../p-input-text/p-input-text.md)
+- [Input Time](../p-input-time/p-input-time.md)
+- [Input Week](../p-input-week/p-input-week.md)
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element. |
+
+### ARIA enhancements
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-describedby="IDREF"` | Defines the accessible description combined with the status message. |
+| `role="status"`, `role="alert"` | When `message` and `state` or `loading` prop change, the status message is announced. |
+| `aria-hidden="true"` | If `required` attribute is set, the visible asterisk indicator is hidden from assistive technologies. |
+| `aria-invalid="true"` | If `error` state is set. |
+| `aria-live="polite"` | If the `maxlength` attribute is present, the counter is announced via ARIA live region. |
+
+## Development considerations
+
+### Disabled state
+
+In general, avoid using the `disabled` state. Disabled elements are no longer focusable and may be missed by screen reader users. They can also confuse sighted users if the reason they are disabled is not made clear.
+
+### Common do's and don'ts
+
+- **Do** keep a persistent label and use helper/description text when additional context is required.
+- **Do** use the component state/message API so validation and status changes are announced.
+- **Do** use clear error wording that helps users recover.
+- **Don't** rely on placeholder text as the only label.
+- **Don't** use `hide-label` without an accessible name.
+
+## Limitations
+
+Due to the nature of **Web Components** and **shadow DOM**, there are limitations when using some **ARIA** attributes to define relationships between elements across different shadow DOMs or shadow DOM/light DOM combinations.
+
+| ARIA | Support |
+| --- | --- |
+| `aria-labelledby` | 🚫 |
+| `aria-describedby` | 🚫 |
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `autoComplete` | `string` | `undefined` | Provides the browser with a URL autofill hint (e.g. `autocomplete='url'`). |
+| `compact` | `boolean` | `false` | Reduces the input height and padding for a more compact layout. |
+| `description` | `string` | `''` | Sets a supplementary description displayed below the label to provide additional context. |
+| `disabled` | `boolean` | `false` | Disables the field, preventing all input. The value is not submitted with the form. |
+| `form` | `string` | `undefined` | Associates the field with a form element by its ID when the field is not nested directly inside it. |
+| `hideLabel` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values. |
+| `indicator` | `boolean` | `false` | Shows a URL/link icon at the start of the field as a visual indicator. |
+| `label` | `string` | `''` | Sets the visible label text displayed above the input field. |
+| `loading` _(experimental)_ | `boolean` | `false` | @experimental Disables the field and displays a loading spinner to indicate an ongoing operation. |
+| `maxLength` | `number` | `undefined` | Sets the maximum number of characters the user can enter. |
+| `message` | `string` | `''` | Sets the validation feedback message displayed below the field when `state` is `success` or `error`. |
+| `minLength` | `number` | `undefined` | Sets the minimum number of characters required for the field to be considered valid. |
+| `name` _(required)_ | `string` | `undefined` | Sets the name submitted with the form data to identify this field's value on the server. |
+| `pattern` | `string` | `undefined` | Sets a regular expression the entered value must match to be valid. Overrides the browser's default URL validation. |
+| `placeholder` | `string` | `''` | Sets placeholder text shown inside the field when it is empty, such as an example URL. |
+| `readOnly` | `boolean` | `false` | Makes the field read-only — the value is displayed but cannot be edited. The value is still submitted with the form. |
+| `required` | `boolean` | `false` | Marks the field as required — form submission is blocked while this field is empty. |
+| `state` | `'none'` `'error'` `'success'` | `'none'` | Sets the validation state, controlling the visual appearance and style of the feedback message (`none`, `success`, `error`). |
+| `value` | `string | null` | `''` | Sets the current URL value. Must be an absolute URL (e.g. `https://porsche.com`) to pass browser validation. |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `blur` | `CustomEvent<InputUrlBlurEventDetail>`<br>`Event` | Emitted when the input loses focus, regardless of whether the value changed. |
+| `change` | `CustomEvent<InputUrlChangeEventDetail>`<br>`Event` | Emitted when the input loses focus after its value was changed. |
+| `input` | `CustomEvent<InputUrlInputEventDetail>`<br>`InputEvent` | Emitted on every value change as the user types. |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| `label` | no | — | Shows a label. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| `label-after` | no | — | Places additional content after the label text (for content that should not be part of the label, e.g. external links or `p-popover`). |
+| `description` | no | — | Shows a description. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| `message` | no | — | Shows a state message. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| `start` | no | — | Shows content at the start of the input (e.g. unit prefix). |
+| `end` | no | — | Shows content at the end of the input (e.g. toggle button, unit suffix). |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--ref-p-input-slotted-padding` | — | When slotting a `p-button-pure` or `p-link-pure` this variable needs to be set as `padding` in oder to adjust the alignment correctly. |
+| `--ref-p-input-slotted-margin` | — | When slotting a `p-button-pure` or `p-link-pure` this variable needs to be set as `margin` in oder to adjust the spacings correctly. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |
+| Form | The `p-input-url` can be integrated into a form in two ways: **controlled** or **uncontrolled**, depending on your needs. | [./examples/Form.tsx](./examples/Form.tsx) |
+| Slots | Use named slots when `label`, `description` or `message` need markup such as a link. | [./examples/Slots.tsx](./examples/Slots.tsx) |

package/skill/references/components/p-input-week/examples/Default.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import { PInputWeek } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PInputWeek label="Some label" name="some-name"></PInputWeek>
+    </>
+  )
+}

package/skill/references/components/p-input-week/examples/Form.tsx

@@ -0,0 +1,45 @@
+import React from 'react';
+import {
+  type InputWeekInputEventDetail,
+  PButton,
+  PInputWeek,
+  type PInputWeekProps,
+  PText,
+} from '@porsche-design-system/components-react';
+import { FormEvent, useState } from 'react';
+
+export const Example = () => {
+  const [form, setForm] = useState({ myInputWeek: '' });
+  const [lastSubmittedData, setLastSubmittedData] = useState<any>();
+
+  const onInput = (e: CustomEvent<InputWeekInputEventDetail>) => {
+    const { name, value } = e.target as HTMLElement & PInputWeekProps;
+    setForm((prev) => ({
+      ...prev,
+      [name]: value,
+    }));
+  };
+
+  const onSubmit = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    setLastSubmittedData(JSON.stringify(form));
+  };
+
+  const onReset = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    setForm({ myInputWeek: '' });
+  };
+
+  return (
+    <>
+      <form onSubmit={onSubmit} onReset={onReset} className="flex flex-col gap-fluid-sm">
+        <PInputWeek name="myInputWeek" label="Some Label" value={form.myInputWeek} onInput={onInput} />
+        <div className="flex gap-fluid-sm">
+          <PButton type="submit">Submit</PButton>
+          <PButton type="reset">Reset</PButton>
+        </div>
+        <PText>Last submitted data: {lastSubmittedData}</PText>
+      </form>
+    </>
+  );
+};

package/skill/references/components/p-input-week/examples/Slots.tsx

@@ -0,0 +1,41 @@
+import React from 'react';
+import { PButtonPure, PIcon, PInputWeek, PPopover } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PInputWeek state="error">
+        <span slot="label" id="some-label-id">
+          Some label with a 
+          <a href="https://designsystem.porsche.com" className="underline">
+            link
+          </a>
+           and a "label-after" slot.
+        </span>
+        <PPopover slot="label-after">
+          Some Popover content with a 
+          <a href="https://designsystem.porsche.com" className="underline">
+            link
+          </a>
+          .
+        </PPopover>
+        <span slot="description" id="some-description-id">
+          Some description with a 
+          <a href="https://designsystem.porsche.com" className="underline">
+            link
+          </a>
+          .
+        </span>
+        <PIcon slot="start" name="shopping-cart" color="contrast-medium" aria-hidden={true}></PIcon>
+        <PButtonPure slot="end" icon="delete" hideLabel={true} className="p-(--ref-p-input-slotted-padding) m-(--ref-p-input-slotted-margin)" aria={{'aria-label': 'Delete'}}></PButtonPure>
+        <span slot="message" id="some-message-id">
+          Some error message with a 
+          <a href="https://designsystem.porsche.com" className="underline">
+            link
+          </a>
+          .
+        </span>
+      </PInputWeek>
+    </>
+  )
+}

package/skill/references/components/p-input-week/p-input-week.md

@@ -0,0 +1,142 @@
+# p-input-week
+
+The `p-input-week` component provides a versatile, user‑friendly interface for entering week values. It supports direct keyboard input, including arrow-key adjustments for precise changes. It has a start and end slot in order to support flexible slotted content.
+
+A `label` is a caption which informs the user what information a particular form field is asking for. The `p-input-week` component can be used with or without a label, but it's recommended to keep the label visible for better accessibility whenever possible. When used without a label, it's mandatory to provide a descriptive label text for screen readers.
+
+> **Input Event Handling**
+>
+> React's `onChange` behaves like the native `onInput` (fires on every keystroke). However, our web components follow standard browser behavior, where `onChange` only fires when the input loses focus. To get real-time updates on each keystroke, use `onInput` instead.
+
+## Usage
+
+`p-input-week` is intended for week input scenarios. It should not be used for values that merely happen to consist of digits. For those cases, consider using another input with an appropriate input mode. For further guidance, see the [MDN documentation on week inputs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/week#using_date_inputs).
+
+### Do:
+
+- Use when a week value is required or optional.
+- Use without a label only when the context is clear.
+- Use for validation and error of input.
+- Use asterisk for required fields.
+
+### Don't:
+
+- Don't use labels with more than two words whenever possible (keep it short and descriptive).
+- Don't use instructional or description text for the label.
+
+---
+
+## Related Components
+
+- [Input Date](../p-input-date/p-input-date.md)
+- [Input Email](../p-input-email/p-input-email.md)
+- [Input Month](../p-input-month/p-input-month.md)
+- [Input Number](../p-input-number/p-input-number.md)
+- [Input Password](../p-input-password/p-input-password.md)
+- [Input Search](../p-input-search/p-input-search.md)
+- [Input Tel](../p-input-tel/p-input-tel.md)
+- [Input Text](../p-input-text/p-input-text.md)
+- [Input Time](../p-input-time/p-input-time.md)
+- [Input Url](../p-input-url/p-input-url.md)
+
+## Accessibility support
+
+### Keyboard
+
+| Key / state | Function |
+| --- | --- |
+| `Tab`, `Shift-Tab` | Moves focus to the next (or previous) focusable element. |
+| `Arrow Up/Down` | Sets increments/decrements in regards of the steps |
+
+### ARIA enhancements
+
+#### Internal **ARIA** that is managed by the component:
+
+| ARIA | Usage |
+| --- | --- |
+| `aria-describedby="IDREF"` | Defines the accessible description combined with the status message. |
+| `role="status"`, `role="alert"` | When `message` and `state` or `loading` prop change, the status message is announced. |
+| `aria-hidden="true"` | If `required` attribute is set, the visible asterisk indicator is hidden from assistive technologies. |
+| `aria-invalid="true"` | If `error` state is set. |
+| `aria-live="polite"` | If the `maxlength` attribute is present, the counter is announced via ARIA live region. |
+
+## Development considerations
+
+### Disabled state
+
+In general, avoid using the `disabled` state. Disabled elements are no longer focusable and may be missed by screen reader users. They can also confuse sighted users if the reason they are disabled is not made clear.
+
+### Common do's and don'ts
+
+- **Do** keep a persistent label and use helper/description text when additional context is required.
+- **Do** use the component state/message API so validation and status changes are announced.
+- **Do** use clear error wording that helps users recover.
+- **Don't** rely on placeholder text as the only label.
+- **Don't** use `hide-label` without an accessible name.
+
+## Limitations
+
+Due to the nature of **Web Components** and **shadow DOM**, there are limitations when using some **ARIA** attributes to define relationships between elements across different shadow DOMs or shadow DOM/light DOM combinations.
+
+| ARIA | Support |
+| --- | --- |
+| `aria-labelledby` | 🚫 |
+| `aria-describedby` | 🚫 |
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `autoComplete` | `string` | `undefined` | Provides the browser with a week/year autofill hint. |
+| `compact` | `boolean` | `false` | Reduces the input height and padding for a more compact layout. |
+| `description` | `string` | `''` | Sets a supplementary description displayed below the label to provide additional context. |
+| `disabled` | `boolean` | `false` | Disables the field, preventing week selection. The value is not submitted with the form. |
+| `form` | `string` | `undefined` | Associates the field with a form element by its ID when the field is not nested directly inside it. |
+| `hideLabel` | `boolean`<br>`BreakpointCustomizable<boolean>` | `false` | Hides the visible label while keeping it accessible to screen readers. Supports responsive breakpoint values. |
+| `label` | `string` | `''` | Sets the visible label text displayed above the input field. |
+| `loading` _(experimental)_ | `boolean` | `false` | @experimental Disables the field and displays a loading spinner to indicate an ongoing operation. |
+| `max` | `string` | `undefined` | Sets the latest selectable week in YYYY-Www format. Weeks after this are disabled in the picker. |
+| `message` | `string` | `''` | Sets the validation feedback message displayed below the field when `state` is `success` or `error`. |
+| `min` | `string` | `undefined` | Sets the earliest selectable week in YYYY-Www format. Weeks before this are disabled in the picker. |
+| `name` _(required)_ | `string` | `undefined` | Sets the name submitted with the form data to identify this field's value on the server. |
+| `readOnly` | `boolean` | `false` | Makes the field read-only — the value is displayed but cannot be changed. The value is still submitted with the form. |
+| `required` | `boolean` | `false` | Marks the field as required — form submission is blocked while no week is selected. |
+| `state` | `'none'` `'error'` `'success'` | `'none'` | Sets the validation state, controlling the visual appearance and style of the feedback message (`none`, `success`, `error`). |
+| `step` | `number` | `1` | Sets the stepping interval in weeks. |
+| `value` | `string | null` | `''` | Sets the current ISO week value in YYYY-Www format (e.g. `2025-W27`). |
+
+### Events
+
+| Event | Type | Description |
+| --- | --- | --- |
+| `blur` | `CustomEvent<InputWeekBlurEventDetail>`<br>`Event` | Emitted when the input loses focus, regardless of whether the value changed. |
+| `change` | `CustomEvent<InputWeekChangeEventDetail>`<br>`Event` | Emitted when the input loses focus after its value was changed. |
+| `input` | `CustomEvent<InputWeekInputEventDetail>`<br>`InputEvent` | Emitted on every value change as the user interacts with the week picker. |
+
+### Slots
+
+| Slot | Required | Allowed tag names | Description |
+| --- | --- | --- | --- |
+| `label` | no | — | Shows a label. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| `label-after` | no | — | Places additional content after the label text (for content that should not be part of the label, e.g. external links or `p-popover`). |
+| `description` | no | — | Shows a description. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| `message` | no | — | Shows a state message. Only [phrasing content](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content) is allowed. |
+| `start` | no | — | Shows content at the start of the input (e.g. unit prefix). |
+| `end` | no | — | Shows content at the end of the input (e.g. toggle button, unit suffix). |
+
+### CSS Variables
+
+| CSS Variable | Default | Description |
+| --- | --- | --- |
+| `--ref-p-input-slotted-padding` | — | When slotting a `p-button-pure` or `p-link-pure` this variable needs to be set as `padding` in oder to adjust the alignment correctly. |
+| `--ref-p-input-slotted-margin` | — | When slotting a `p-button-pure` or `p-link-pure` this variable needs to be set as `margin` in oder to adjust the spacings correctly. |
+
+## Examples
+
+| Example | When to use | File |
+| --- | --- | --- |
+| Default | Minimal default configuration. | [./examples/Default.tsx](./examples/Default.tsx) |
+| Form | The `p-input-week` can be integrated into a form in two ways: **controlled** or **uncontrolled**, depending on your needs. | [./examples/Form.tsx](./examples/Form.tsx) |
+| Slots | Use named slots when `label`, `description` or `message` need markup such as a link. | [./examples/Slots.tsx](./examples/Slots.tsx) |

package/skill/references/components/p-link/examples/Default.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+import { PLink } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PLink href="https://porsche.com">
+        Some label
+      </PLink>
+    </>
+  )
+}