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

package/skills/pds-knowledge-react/references/components/p-select/accessibility.md

@@ -0,0 +1,140 @@
+# p-select accessibility integration examples
+
+## Integration examples
+
+### Prompt option used instead of a label
+
+#### ❌ Anti-pattern
+
+```tsx
+<PSelect name="model">
+  <PSelectOption value="">
+    Select a model
+  </PSelectOption>
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+  <PSelectOption value="carrera-s">
+    911 Carrera S
+  </PSelectOption>
+</PSelect>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PSelect label="Porsche model" name="model" description="Choose the model for your configuration.">
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+  <PSelectOption value="carrera-s">
+    911 Carrera S
+  </PSelectOption>
+</PSelect>
+```
+
+### Ambiguous option labels without field context
+
+#### ❌ Anti-pattern
+
+```tsx
+<PSelect label="Model" name="model">
+  <PSelectOption value="base">
+    Base
+  </PSelectOption>
+  <PSelectOption value="s">
+    S
+  </PSelectOption>
+</PSelect>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PSelect label="Porsche 911 trim" name="model" description="Select the trim level for your configuration.">
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+  <PSelectOption value="carrera-s">
+    911 Carrera S
+  </PSelectOption>
+</PSelect>
+```
+
+### Hidden label without accessible name
+
+#### ❌ Anti-pattern
+
+```tsx
+<PSelect name="model" hideLabel={true}>
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+</PSelect>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PSelect label="Porsche model" name="model" hideLabel={true}>
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+</PSelect>
+```
+
+### Validation feedback via state and message API
+
+#### ❌ Anti-pattern
+
+```tsx
+<PSelect label="Porsche model" name="model" aria-invalid={true} message="Required">
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+  <PSelectOption value="carrera-s">
+    911 Carrera S
+  </PSelectOption>
+</PSelect>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PSelect label="Porsche model" name="model" state="error" message="Select a model to continue with your configuration.">
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+  <PSelectOption value="carrera-s">
+    911 Carrera S
+  </PSelectOption>
+</PSelect>
+```
+
+### Error state without recovery guidance
+
+#### ❌ Anti-pattern
+
+```tsx
+<PSelect label="Porsche model" name="model" state="error" message="Invalid">
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+  <PSelectOption value="carrera-s">
+    911 Carrera S
+  </PSelectOption>
+</PSelect>
+```
+
+#### ✅ Recommended
+
+```tsx
+<PSelect label="Porsche model" name="model" required={true} state="error" message="Select a Porsche model. This field is required to continue.">
+  <PSelectOption value="carrera">
+    911 Carrera
+  </PSelectOption>
+  <PSelectOption value="carrera-s">
+    911 Carrera S
+  </PSelectOption>
+</PSelect>
+```

package/skills/pds-knowledge-react/references/components/p-select/examples/AsyncFilter.tsx

@@ -0,0 +1,136 @@
+import React from 'react';
+import {
+  type InputSearchInputEventDetail,
+  PIcon,
+  PInputSearch,
+  PSelect,
+  PSelectOption,
+  type PSelectProps,
+  type SelectChangeEventDetail,
+  type SelectToggleEventDetail,
+} from '@porsche-design-system/components-react';
+import { useCallback, useRef, useState } from 'react';
+
+const useDebounce = <T,>(callback: (value: T) => void, delay = 400) => {
+  const timer = useRef<number | undefined>(undefined);
+  return (value: T) => {
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = window.setTimeout(() => callback(value), delay);
+  };
+};
+
+export const Example = () => {
+  const [value, setValue] = useState<PSelectProps['value']>(undefined);
+  const [options, setOptions] = useState<{ value: string; label: string }[]>([]);
+
+  const [searchValue, setSearchValue] = useState('');
+  const [initialLoading, setInitialLoading] = useState(false);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const hasLoadedOnce = useRef(false);
+  const currentFetchId = useRef(0);
+
+  // 💡Consider using a data-fetching library like React Query or SWR here.
+  // They provide built-in caching, deduplication, retries, and loading/error state management,
+  // which would make this async logic cleaner and more reliable than manual fetch handling.
+  const fetchOptions = useCallback(async (term?: string, isInitial?: boolean) => {
+    const fetchId = ++currentFetchId.current;
+    isInitial ? setInitialLoading(true) : setLoading(true);
+    try {
+      const url = term
+        ? `https://jsonplaceholder.typicode.com/users?username_like=${term}`
+        : `https://jsonplaceholder.typicode.com/users`;
+
+      const res = await fetch(url);
+      const data: { id: number; name: string; username: string }[] = await res.json();
+
+      // Ignore stale results
+      if (fetchId !== currentFetchId.current) return;
+
+      const newOptions = data.map((user) => ({
+        value: user.id.toString(),
+        label: `${user.name} (${user.username})`,
+      }));
+
+      setOptions(newOptions);
+      setError(null);
+      hasLoadedOnce.current = true;
+    } catch (err) {
+      console.error('Failed to fetch options', err);
+      setOptions([]);
+      setError('Failed to load options');
+    } finally {
+      isInitial ? setInitialLoading(false) : setLoading(false);
+    }
+  }, []);
+
+  const debouncedFetch = useDebounce(fetchOptions, 400);
+
+  const onInput = (e: CustomEvent<InputSearchInputEventDetail>) => {
+    const term = (e.target as HTMLElement & { value: string }).value;
+    setSearchValue(term);
+    debouncedFetch(term.trim() || undefined);
+  };
+
+  const onChange = (e: CustomEvent<SelectChangeEventDetail>) => {
+    setValue((e.target as HTMLElement & { value: string }).value);
+  };
+
+  const onToggle = async (e: CustomEvent<SelectToggleEventDetail>) => {
+    if (e.detail.open && !hasLoadedOnce.current) {
+      fetchOptions(undefined, true);
+    }
+  };
+
+  return (
+    <PSelect name="async-search-select" label="Async Search" value={value} onChange={onChange} onToggle={onToggle}>
+      <PInputSearch
+        slot="filter"
+        name="search"
+        value={searchValue}
+        loading={loading}
+        clear
+        indicator
+        compact
+        autoComplete="off"
+        onInput={onInput}
+        // Prevent bubbling
+        onBlur={(e: any) => e.stopPropagation()}
+        onChange={(e: any) => e.stopPropagation()}
+      />
+
+      {/* Initial skeleton loading */}
+      {initialLoading &&
+        !error &&
+        Array.from({ length: 9 }).map((_, i) => <div key={i} slot="options-status" className="skeleton h-[40px]" />)}
+
+      {/* Options */}
+      {options.map((opt) => (
+        <PSelectOption key={opt.value} value={opt.value}>
+          {opt.label}
+        </PSelectOption>
+      ))}
+
+      {/* No filter results */}
+      {!initialLoading && options.length === 0 && !error && (
+        <div
+          slot="options-status"
+          className="text-contrast-medium cursor-not-allowed py-static-sm px-[12px]"
+          role="alert"
+        >
+          <span aria-hidden="true">–</span>
+          <span className="sr-only">No results found</span>
+        </div>
+      )}
+
+      {/* Error state */}
+      {error && (
+        <div slot="options-status" className="flex gap-static-sm py-static-sm px-[12px]" role="alert">
+          <PIcon name="information" color="error" />
+          <span className="text-error">{error}</span>
+        </div>
+      )}
+    </PSelect>
+  );
+};

package/skills/pds-knowledge-react/references/components/p-select/examples/Default.tsx

@@ -0,0 +1,29 @@
+import React from 'react';
+import { PSelect, PSelectOption } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PSelect name="options" label="Some Label" description="Some description">
+        <PSelectOption value="a">
+          Option A
+        </PSelectOption>
+        <PSelectOption value="b">
+          Option B
+        </PSelectOption>
+        <PSelectOption value="c">
+          Option C
+        </PSelectOption>
+        <PSelectOption value="d">
+          Option D
+        </PSelectOption>
+        <PSelectOption value="e">
+          Option E
+        </PSelectOption>
+        <PSelectOption value="f">
+          Option F
+        </PSelectOption>
+      </PSelect>
+    </>
+  )
+}

package/skills/pds-knowledge-react/references/components/p-select/examples/Form.tsx

@@ -0,0 +1,53 @@
+import React from 'react';
+import {
+  PButton,
+  PSelect,
+  PSelectOption,
+  type PSelectProps,
+  PText,
+  type SelectChangeEventDetail,
+} from '@porsche-design-system/components-react';
+import { FormEvent, useState } from 'react';
+
+export const Example = () => {
+  const [form, setForm] = useState({ mySelect: undefined });
+  const [lastSubmittedData, setLastSubmittedData] = useState<any>();
+
+  const onChange = (e: CustomEvent<SelectChangeEventDetail>) => {
+    const { name, value } = e.target as HTMLElement & PSelectProps;
+    setForm((prev) => ({
+      ...prev,
+      [name]: value,
+    }));
+  };
+
+  const onSubmit = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    setLastSubmittedData(JSON.stringify(form));
+  };
+
+  const onReset = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    setForm({ mySelect: undefined });
+  };
+
+  return (
+    <>
+      <form onSubmit={onSubmit} onReset={onReset} className="flex flex-col gap-fluid-sm">
+        <PSelect name="mySelect" label="Some Label" value={form.mySelect} onChange={onChange}>
+          <PSelectOption value="a">Option A</PSelectOption>
+          <PSelectOption value="b">Option B</PSelectOption>
+          <PSelectOption value="c">Option C</PSelectOption>
+          <PSelectOption value="d">Option D</PSelectOption>
+          <PSelectOption value="e">Option E</PSelectOption>
+          <PSelectOption value="f">Option F</PSelectOption>
+        </PSelect>
+        <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/skills/pds-knowledge-react/references/components/p-select/examples/Optgroups.tsx

@@ -0,0 +1,42 @@
+import React from 'react';
+import { POptgroup, PSelect, PSelectOption } from '@porsche-design-system/components-react';
+
+export const Example = () => {
+  return (
+    <>
+      <PSelect name="options" label="Some Label" description="Some description">
+        <POptgroup label="Some optgroup label 1">
+          <PSelectOption value="a">
+            Option A
+          </PSelectOption>
+          <PSelectOption value="b">
+            Option B
+          </PSelectOption>
+          <PSelectOption value="c">
+            Option C
+          </PSelectOption>
+          <PSelectOption value="d">
+            Option D
+          </PSelectOption>
+          <PSelectOption value="e">
+            Option E
+          </PSelectOption>
+          <PSelectOption value="f">
+            Option F
+          </PSelectOption>
+        </POptgroup>
+        <POptgroup label="Some optgroup label 2">
+          <PSelectOption value="g">
+            Option G
+          </PSelectOption>
+          <PSelectOption value="h">
+            Option H
+          </PSelectOption>
+          <PSelectOption value="i">
+            Option I
+          </PSelectOption>
+        </POptgroup>
+      </PSelect>
+    </>
+  )
+}

package/skills/pds-knowledge-react/references/components/p-select/examples/Required.tsx

@@ -0,0 +1,48 @@
+import React from 'react';
+import { PButton, PCheckbox, PSelect, PSelectOption, PText } from '@porsche-design-system/components-react';
+import { type SubmitEvent, useState } from 'react';
+
+export const Example = () => {
+  const [lastSubmittedData, setLastSubmittedData] = useState('none');
+  const [isRequired, setIsRequired] = useState(true);
+  const [hasDeselection, setHasDeselection] = useState(false);
+
+  const onChangeRequired = () => {
+    setIsRequired((prev) => !prev);
+  };
+
+  const onChangeDeselection = () => {
+    setHasDeselection((prev) => !prev);
+  };
+
+  const onSubmit = (e: SubmitEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    setLastSubmittedData(formData.get('options')?.toString() || 'none');
+  };
+
+  return (
+    <>
+      <div className="flex flex-col gap-static-sm">
+        <PCheckbox label="Required" name="required" checked={isRequired} onChange={onChangeRequired} />
+        <PCheckbox
+          label="Allow deselection"
+          name="deselection"
+          checked={hasDeselection}
+          onChange={onChangeDeselection}
+        />
+      </div>
+      <form onSubmit={onSubmit} className="flex flex-col gap-fluid-sm mt-fluid-sm">
+        <PSelect name="options" label="Some Label" required={isRequired}>
+          {hasDeselection && <PSelectOption></PSelectOption>}
+          <PSelectOption value="1">Option 1</PSelectOption>
+          <PSelectOption value="2">Option 2</PSelectOption>
+          <PSelectOption value="3">Option 3</PSelectOption>
+        </PSelect>
+        <PButton type="submit">Submit</PButton>
+      </form>
+
+      <PText>Last submitted data: {lastSubmittedData}</PText>
+    </>
+  );
+};

package/skills/pds-knowledge-react/references/components/p-select/examples/SelectedSlot.tsx

@@ -0,0 +1,124 @@
+import React from 'react';
+import {
+  PFlag,
+  type PFlagProps,
+  POptgroup,
+  PSelect,
+  PSelectOption,
+  type PSelectProps,
+  type SelectChangeEventDetail,
+} from '@porsche-design-system/components-react';
+import { useState } from 'react';
+
+type Option = { label: string; code: PFlagProps['name']; continent: string };
+
+const optionsData: Option[] = [
+  {
+    label: 'China',
+    code: 'cn',
+    continent: 'Asia',
+  },
+  {
+    label: 'Japan',
+    code: 'jp',
+    continent: 'Asia',
+  },
+  {
+    label: 'South Korea',
+    code: 'kr',
+    continent: 'Asia',
+  },
+  {
+    label: 'Austria',
+    code: 'at',
+    continent: 'Europe',
+  },
+  {
+    label: 'France',
+    code: 'fr',
+    continent: 'Europe',
+  },
+  {
+    label: 'Germany',
+    code: 'de',
+    continent: 'Europe',
+  },
+  {
+    label: 'Great Britain',
+    code: 'gb',
+    continent: 'Europe',
+  },
+  {
+    label: 'Italy',
+    code: 'it',
+    continent: 'Europe',
+  },
+  {
+    label: 'Portugal',
+    code: 'pt',
+    continent: 'Europe',
+  },
+  {
+    label: 'Spain',
+    code: 'es',
+    continent: 'Europe',
+  },
+
+  {
+    label: 'Canada',
+    code: 'ca',
+    continent: 'North America',
+  },
+  {
+    label: 'USA',
+    code: 'us',
+    continent: 'North America',
+  },
+];
+
+export const Example = () => {
+  const [value, setValue] = useState<PSelectProps['value']>(undefined);
+  const [options] = useState<Option[]>(optionsData);
+  const [selectedOption, setSelectedOption] = useState<Option | undefined>(undefined);
+
+  const optgroups: Record<string, Option[]> = options.reduce(
+    (acc, item) => {
+      const key = item.continent;
+      if (!acc[key]) acc[key] = [];
+      acc[key].push(item);
+      return acc;
+    },
+    {} as Record<string, Option[]>
+  );
+
+  const onChange = (e: CustomEvent<SelectChangeEventDetail>) => {
+    const value = (e.target as HTMLElement & { value: string }).value;
+    setValue(value);
+    setSelectedOption(options.find((option) => option.code === value));
+  };
+
+  return (
+    <PSelect name="selected-slot-select" label="Selected Slot" value={value} onChange={onChange}>
+      <span slot="selected" className="h-full flex items-center gap-fluid-sm grow">
+        {selectedOption && (
+          <>
+            <PFlag name={selectedOption.code}></PFlag>
+            <p className="prose-text-sm truncate m-0">{selectedOption.label}</p>
+          </>
+        )}
+      </span>
+      {Object.entries(optgroups).map(([continent, options]) => (
+        <POptgroup key={continent} label={continent}>
+          {options.map((option) => (
+            <PSelectOption key={option.code} value={option.code}>
+              <div className="w-full flex items-center gap-fluid-sm">
+                <PFlag name={option.code}></PFlag>
+                <p className="prose-text-sm m-0">{option.label}</p>
+              </div>
+            </PSelectOption>
+          ))}
+        </POptgroup>
+      ))}
+    </PSelect>
+  );
+};

package/skills/pds-knowledge-react/references/components/p-select/examples/SetValue.tsx

@@ -0,0 +1,80 @@
+import React from 'react';
+import {
+  type InputTextInputEventDetail,
+  PButton,
+  PInputText,
+  PSelect,
+  PSelectOption,
+  type PSelectProps,
+  SelectChangeEventDetail,
+} from '@porsche-design-system/components-react';
+import { useState } from 'react';
+
+export const Example = () => {
+  const [selectedValue, setSelectedValue] = useState<PSelectProps['value']>('1');
+  const [inputValue, setInputValue] = useState('');
+  const [optionCount, setOptionCount] = useState(3);
+
+  const onChangeInput = (e: CustomEvent<InputTextInputEventDetail>) => {
+    setInputValue((e.detail.target as HTMLInputElement).value);
+  };
+
+  const onSetValue = () => {
+    setSelectedValue(inputValue);
+  };
+
+  const onResetValue = () => {
+    setSelectedValue('1');
+    setInputValue('');
+  };
+
+  const onChange = (e: CustomEvent<SelectChangeEventDetail>) => {
+    setSelectedValue(e.detail.value);
+    setInputValue(String(e.detail.value ?? ''));
+  };
+
+  const onAddOption = () => {
+    setOptionCount((prev) => prev + 1);
+  };
+
+  const onRemoveOption = () => {
+    if (optionCount > 0) {
+      setOptionCount((prev) => prev - 1);
+    }
+  };
+
+  return (
+    <div className="flex flex-col gap-fluid-sm">
+      <PInputText
+        name="input-value"
+        label="Value:"
+        placeholder="e.g. 1"
+        value={inputValue}
+        onInput={(e) => onChangeInput(e as CustomEvent<InputTextInputEventDetail>)}
+      />
+      <div className="flex gap-fluid-sm">
+        <PButton type="button" onClick={onSetValue} compact={true}>
+          Set Value
+        </PButton>
+        <PButton type="button" onClick={onResetValue} compact={true}>
+          Reset value
+        </PButton>
+      </div>
+      <PSelect name="options" label="Some Label" value={selectedValue} onChange={onChange}>
+        {[...Array(optionCount).keys()].map((idx) => (
+          <PSelectOption key={idx} value={`${idx + 1}`}>
+            Option {idx + 1}
+          </PSelectOption>
+        ))}
+      </PSelect>
+      <div className="flex gap-fluid-sm">
+        <PButton type="button" onClick={onAddOption} compact={true}>
+          Add option
+        </PButton>
+        <PButton type="button" onClick={onRemoveOption} compact={true}>
+          Remove last option
+        </PButton>
+      </div>
+    </div>
+  );
+};