@pine-ds/core 3.27.0 → 3.28.0

package/dist/types/components.d.ts

@@ -12,6 +12,7 @@ import { ChipSentimentType, ChipSizeType, ChipVariantType, PlacementType } from
 import { ComboboxLoadOptionsEventDetail, ComboboxOption, ComboboxSearchEventDetail } from "./components/pds-combobox/combobox-interface";
 import { PdsFilterClearEventDetail, PdsFilterCloseEventDetail, PdsFilterOpenEventDetail, PdsFilterVariant } from "./components/pds-filters/pds-filter/filter-interface";
 import { InputChangeEventDetail, InputInputEventDetail } from "./components/pds-input/input-interface";
+import { PluralForms } from "./i18n";
 import { MultiselectChangeEventDetail, MultiselectCreateEventDetail, MultiselectLoadOptionsEventDetail, MultiselectOption, MultiselectSearchEventDetail } from "./components/pds-multiselect/multiselect-interface";
 import { PdsPopoverEventDetail } from "./components/pds-popover/popover-interface";
 import { RadioGroupChangeEventDetail } from "./components/pds-radio-group/radio-group-interface";
@@ -24,6 +25,7 @@ export { ChipSentimentType, ChipSizeType, ChipVariantType, PlacementType } from
 export { ComboboxLoadOptionsEventDetail, ComboboxOption, ComboboxSearchEventDetail } from "./components/pds-combobox/combobox-interface";
 export { PdsFilterClearEventDetail, PdsFilterCloseEventDetail, PdsFilterOpenEventDetail, PdsFilterVariant } from "./components/pds-filters/pds-filter/filter-interface";
 export { InputChangeEventDetail, InputInputEventDetail } from "./components/pds-input/input-interface";
+export { PluralForms } from "./i18n";
 export { MultiselectChangeEventDetail, MultiselectCreateEventDetail, MultiselectLoadOptionsEventDetail, MultiselectOption, MultiselectSearchEventDetail } from "./components/pds-multiselect/multiselect-interface";
 export { PdsPopoverEventDetail } from "./components/pds-popover/popover-interface";
 export { RadioGroupChangeEventDetail } from "./components/pds-radio-group/radio-group-interface";
@@ -85,6 +87,11 @@ export namespace Components {
           * A unique identifier used for the underlying component `id` attribute.
          */
         "componentId": string;
+        /**
+          * Accessible label for the dismiss button. Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'Dismiss alert'
+         */
+        "dismissLabel": string;
         /**
           * If true, shows the dismiss button. If false, the dismiss button is hidden.
           * @defaultValue false
@@ -150,6 +157,11 @@ export namespace Components {
   | 'sm' // 32px
   | 'xs' // 24px
   | string;
+        /**
+          * Accessible label for the dropdown trigger button. Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'Avatar dropdown trigger'
+         */
+        "triggerLabel": string;
         /**
           * Determines the variant of avatar. Changes appearance accordingly.
           * @defaultValue customer
@@ -838,6 +850,11 @@ export namespace Components {
           * A unique identifier used for the underlying component `id` attribute.
          */
         "componentId": string;
+        /**
+          * Accessible label for the remove button. Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'Remove'
+         */
+        "dismissLabel": string;
         /**
           * Determines whether a dot should be displayed on the chip. Note: This prop is ignored when sentiment is 'brand'.
           * @defaultValue false
@@ -1485,6 +1502,16 @@ export namespace Components {
           * A unique identifier used for the underlying component `id` attribute.
          */
         "componentId": string;
+        /**
+          * Accessible label for the create-new-option row. Pass a translated string to localize it; `{text}` is interpolated.
+          * @defaultValue 'Create new tag: {text}'
+         */
+        "createOptionAriaLabel": string;
+        /**
+          * Visible label for the create-new-option row. Pass a translated string to localize it; `{text}` is interpolated.
+          * @defaultValue 'Add "{text}"'
+         */
+        "createOptionLabel": string;
         /**
           * URL endpoint for creating new options. When set, shows "Add" option when no matches found.
          */
@@ -1539,6 +1566,11 @@ export namespace Components {
           * If true, the multiselect is in an invalid state.
          */
         "invalid"?: boolean;
+        /**
+          * Screen-reader announcement when an item is removed. Pass a translated string to localize it; `{item}` is interpolated.
+          * @defaultValue '{item} removed'
+         */
+        "itemRemovedLabel": string;
         /**
           * Text to be displayed as the multiselect label.
          */
@@ -1571,10 +1603,20 @@ export namespace Components {
           * Specifies the name. Submitted with the form as part of a name/value pair.
          */
         "name"?: string;
+        /**
+          * Text shown when no options match the search. Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'No options found'
+         */
+        "noOptionsFoundLabel": string;
         /**
           * Options provided externally (for consumer-managed async). When using `group` on options, keep each group block contiguous in the array. The same `group` label appearing again after other items produces a separate header (same as native `<optgroup>`).
          */
         "options"?: MultiselectOption[];
+        /**
+          * Accessible label for the options listbox (falls back to this when `label` is unset). Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'Options'
+         */
+        "optionsLabel": string;
         /**
           * Width of the dropdown panel. Defaults to the trigger width.
          */
@@ -1585,25 +1627,55 @@ export namespace Components {
          */
         "pillPosition": 'inline' | 'below';
         /**
-          * Placeholder text for the input field.
-          * @default 'Select...'
+          * Accessible label for the remove button on each selected-item pill. Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'Remove'
          */
-        "placeholder"?: string;
+        "pillRemoveLabel": string;
+        /**
+          * Placeholder text for the input field. Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'Select...'
+         */
+        "placeholder": string;
         /**
           * If true, the multiselect is required.
           * @default false
          */
         "required": boolean;
         /**
-          * Placeholder text for the search input inside the dropdown panel.
-          * @default 'Find...'
+          * Accessible label for the search input. Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'Search options'
+         */
+        "searchOptionsLabel": string;
+        /**
+          * Placeholder text for the search input inside the dropdown panel. Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'Find...'
          */
         "searchPlaceholder": string;
+        /**
+          * Singular form of the selected-count trigger text. Pass a translated string to localize it; `{count}` is interpolated.
+          * @defaultValue '{count} item'
+         */
+        "selectedCountLabelOne": string;
+        /**
+          * Plural (and fallback) form of the selected-count trigger text — used for English and any locale whose selected plural category isn't supplied via `selectedCountLabels`. Pass a translated string to localize it; `{count}` is interpolated.
+          * @defaultValue '{count} items'
+         */
+        "selectedCountLabelOther": string;
+        /**
+          * Full CLDR plural forms for the selected-count trigger text, for locales with more than the English `one`/`other` categories (e.g. Polish `few`/`many`, Arabic `zero`/`two`). Accepts an object property or a JSON string attribute keyed by CLDR category — `{ one, other, few, many, two, zero }`. Any form omitted here falls back to `selectedCountLabelOne`/`selectedCountLabelOther`. `{count}` is interpolated.
+          * @defaultValue undefined
+         */
+        "selectedCountLabels"?: PluralForms | string;
         /**
           * Display mode for selected items outside the dropdown panel. `'count'` shows "N item(s)" text in the trigger (default). `'pill'` renders selected items as dismissible pds-chip tags.
           * @default 'count'
          */
         "selectedDisplay": 'count' | 'pill';
+        /**
+          * Accessible label for the selected-items region. Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'Selected items'
+         */
+        "selectedItemsLabel": string;
         /**
           * Sets focus on the trigger button.
          */
@@ -2203,6 +2275,11 @@ export namespace Components {
           * Specifies if and how the browser provides `autocomplete` assistance for the field.
          */
         "autocomplete": string;
+        /**
+          * Template for the character-counter's accessible label. Pass a translated string to localize it; `{current}` and `{max}` are interpolated.
+          * @defaultValue '{current} of {max} characters'
+         */
+        "characterCountLabel": string;
         /**
           * A unique identifier used for the underlying component `id` attribute.
          */
@@ -2284,6 +2361,11 @@ export namespace Components {
          */
         "componentId": string;
         "dismiss": () => Promise<void>;
+        /**
+          * Accessible label for the dismiss button. Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'Dismiss message'
+         */
+        "dismissLabel": string;
         /**
           * Whether the toast can be dismissed manually via the close button. Note: This only controls manual dismissal. Auto-dismissal via duration still applies.
           * @default true
@@ -3185,6 +3267,11 @@ declare namespace LocalJSX {
           * A unique identifier used for the underlying component `id` attribute.
          */
         "componentId"?: string;
+        /**
+          * Accessible label for the dismiss button. Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'Dismiss alert'
+         */
+        "dismissLabel"?: string;
         /**
           * If true, shows the dismiss button. If false, the dismiss button is hidden.
           * @defaultValue false
@@ -3254,6 +3341,11 @@ declare namespace LocalJSX {
   | 'sm' // 32px
   | 'xs' // 24px
   | string;
+        /**
+          * Accessible label for the dropdown trigger button. Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'Avatar dropdown trigger'
+         */
+        "triggerLabel"?: string;
         /**
           * Determines the variant of avatar. Changes appearance accordingly.
           * @defaultValue customer
@@ -3952,6 +4044,11 @@ declare namespace LocalJSX {
           * A unique identifier used for the underlying component `id` attribute.
          */
         "componentId"?: string;
+        /**
+          * Accessible label for the remove button. Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'Remove'
+         */
+        "dismissLabel"?: string;
         /**
           * Determines whether a dot should be displayed on the chip. Note: This prop is ignored when sentiment is 'brand'.
           * @defaultValue false
@@ -4635,6 +4732,16 @@ declare namespace LocalJSX {
           * A unique identifier used for the underlying component `id` attribute.
          */
         "componentId": string;
+        /**
+          * Accessible label for the create-new-option row. Pass a translated string to localize it; `{text}` is interpolated.
+          * @defaultValue 'Create new tag: {text}'
+         */
+        "createOptionAriaLabel"?: string;
+        /**
+          * Visible label for the create-new-option row. Pass a translated string to localize it; `{text}` is interpolated.
+          * @defaultValue 'Add "{text}"'
+         */
+        "createOptionLabel"?: string;
         /**
           * URL endpoint for creating new options. When set, shows "Add" option when no matches found.
          */
@@ -4693,6 +4800,11 @@ declare namespace LocalJSX {
           * If true, the multiselect is in an invalid state.
          */
         "invalid"?: boolean;
+        /**
+          * Screen-reader announcement when an item is removed. Pass a translated string to localize it; `{item}` is interpolated.
+          * @defaultValue '{item} removed'
+         */
+        "itemRemovedLabel"?: string;
         /**
           * Text to be displayed as the multiselect label.
          */
@@ -4725,6 +4837,11 @@ declare namespace LocalJSX {
           * Specifies the name. Submitted with the form as part of a name/value pair.
          */
         "name"?: string;
+        /**
+          * Text shown when no options match the search. Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'No options found'
+         */
+        "noOptionsFoundLabel"?: string;
         /**
           * Emitted when selection changes.
          */
@@ -4749,6 +4866,11 @@ declare namespace LocalJSX {
           * Options provided externally (for consumer-managed async). When using `group` on options, keep each group block contiguous in the array. The same `group` label appearing again after other items produces a separate header (same as native `<optgroup>`).
          */
         "options"?: MultiselectOption[];
+        /**
+          * Accessible label for the options listbox (falls back to this when `label` is unset). Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'Options'
+         */
+        "optionsLabel"?: string;
         /**
           * Width of the dropdown panel. Defaults to the trigger width.
          */
@@ -4759,8 +4881,13 @@ declare namespace LocalJSX {
          */
         "pillPosition"?: 'inline' | 'below';
         /**
-          * Placeholder text for the input field.
-          * @default 'Select...'
+          * Accessible label for the remove button on each selected-item pill. Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'Remove'
+         */
+        "pillRemoveLabel"?: string;
+        /**
+          * Placeholder text for the input field. Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'Select...'
          */
         "placeholder"?: string;
         /**
@@ -4769,15 +4896,40 @@ declare namespace LocalJSX {
          */
         "required"?: boolean;
         /**
-          * Placeholder text for the search input inside the dropdown panel.
-          * @default 'Find...'
+          * Accessible label for the search input. Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'Search options'
+         */
+        "searchOptionsLabel"?: string;
+        /**
+          * Placeholder text for the search input inside the dropdown panel. Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'Find...'
          */
         "searchPlaceholder"?: string;
+        /**
+          * Singular form of the selected-count trigger text. Pass a translated string to localize it; `{count}` is interpolated.
+          * @defaultValue '{count} item'
+         */
+        "selectedCountLabelOne"?: string;
+        /**
+          * Plural (and fallback) form of the selected-count trigger text — used for English and any locale whose selected plural category isn't supplied via `selectedCountLabels`. Pass a translated string to localize it; `{count}` is interpolated.
+          * @defaultValue '{count} items'
+         */
+        "selectedCountLabelOther"?: string;
+        /**
+          * Full CLDR plural forms for the selected-count trigger text, for locales with more than the English `one`/`other` categories (e.g. Polish `few`/`many`, Arabic `zero`/`two`). Accepts an object property or a JSON string attribute keyed by CLDR category — `{ one, other, few, many, two, zero }`. Any form omitted here falls back to `selectedCountLabelOne`/`selectedCountLabelOther`. `{count}` is interpolated.
+          * @defaultValue undefined
+         */
+        "selectedCountLabels"?: PluralForms | string;
         /**
           * Display mode for selected items outside the dropdown panel. `'count'` shows "N item(s)" text in the trigger (default). `'pill'` renders selected items as dismissible pds-chip tags.
           * @default 'count'
          */
         "selectedDisplay"?: 'count' | 'pill';
+        /**
+          * Accessible label for the selected-items region. Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'Selected items'
+         */
+        "selectedItemsLabel"?: string;
         /**
           * Width of the trigger button (and reference for dropdown positioning).
           * @default '100%'
@@ -5402,6 +5554,11 @@ declare namespace LocalJSX {
           * Specifies if and how the browser provides `autocomplete` assistance for the field.
          */
         "autocomplete"?: string;
+        /**
+          * Template for the character-counter's accessible label. Pass a translated string to localize it; `{current}` and `{max}` are interpolated.
+          * @defaultValue '{current} of {max} characters'
+         */
+        "characterCountLabel"?: string;
         /**
           * A unique identifier used for the underlying component `id` attribute.
          */
@@ -5502,6 +5659,11 @@ declare namespace LocalJSX {
           * A unique identifier used for the underlying component `id` attribute.
          */
         "componentId": string;
+        /**
+          * Accessible label for the dismiss button. Pass a translated string to localize it; defaults to English.
+          * @defaultValue 'Dismiss message'
+         */
+        "dismissLabel"?: string;
         /**
           * Whether the toast can be dismissed manually via the close button. Note: This only controls manual dismissal. Auto-dismissal via duration still applies.
           * @default true
@@ -5580,6 +5742,7 @@ declare namespace LocalJSX {
         "dismissible": boolean;
         "hideIcon": boolean;
         "variant": 'default' | 'danger' | 'info' | 'success' | 'warning';
+        "dismissLabel": string;
     }
     interface PdsAvatarAttributes {
         "alt": string | null;
@@ -5595,6 +5758,7 @@ declare namespace LocalJSX {
   | 'xs' // 24px
   | string;
         "variant": 'customer' | 'admin';
+        "triggerLabel": string;
     }
     interface PdsBoxAttributes {
         "alignItems": `start` | `center` | `end` | `baseline` | `stretch`;
@@ -5757,6 +5921,7 @@ declare namespace LocalJSX {
         "removeUrl": string;
         "removeHttpMethod": 'get' | 'post' | 'put' | 'patch' | 'delete';
         "removeTarget": '_blank' | '_self' | '_parent' | '_top';
+        "dismissLabel": string;
     }
     interface PdsComboboxAttributes {
         "componentId": string;
@@ -5909,6 +6074,17 @@ declare namespace LocalJSX {
         "label": string;
         "placeholder": string;
         "searchPlaceholder": string;
+        "searchOptionsLabel": string;
+        "selectedItemsLabel": string;
+        "optionsLabel": string;
+        "noOptionsFoundLabel": string;
+        "createOptionLabel": string;
+        "createOptionAriaLabel": string;
+        "itemRemovedLabel": string;
+        "pillRemoveLabel": string;
+        "selectedCountLabelOne": string;
+        "selectedCountLabelOther": string;
+        "selectedCountLabels": PluralForms | string;
         "closePanelOnSelect": boolean;
         "name": string;
         "disabled": boolean;
@@ -6118,6 +6294,7 @@ declare namespace LocalJSX {
         "maxLength": number;
         "highlight": boolean;
         "value": string | null;
+        "characterCountLabel": string;
     }
     interface PdsToastAttributes {
         "componentId": string;
@@ -6125,6 +6302,7 @@ declare namespace LocalJSX {
         "duration": number;
         "icon": string;
         "type": 'default' | 'danger' | 'loading';
+        "dismissLabel": string;
     }
     interface PdsTooltipAttributes {
         "content": string;

package/dist/types/i18n/i18n-format.d.ts

@@ -0,0 +1,38 @@
+export type I18nVars = Record<string, string | number>;
+export type PluralForms = Partial<Record<Intl.LDMLPluralRule, string>>;
+/**
+ * i18n formatting helpers for Pine components.
+ *
+ * Pine stays string-agnostic: user-facing text is supplied by the consumer as
+ * props (English-defaulted). These helpers only handle the two things a prop
+ * value can't express on its own — interpolating live component state into a
+ * translated template, and picking the right plural form. No stored strings, no
+ * locale registry; the locale is read from the DOM (`lang`), the web-standard
+ * signal a consumer already sets.
+ *
+ * Two limitations of DOM-`lang` locale resolution, both inherent to inferring
+ * locale from the DOM rather than being told it:
+ *
+ * 1. Not reactive. `resolveLocale` is read during render; Stencil has no
+ *    reactive dependency on a DOM attribute, so changing `lang` at runtime
+ *    (`document.documentElement.lang = 'pl'`) does NOT re-render mounted
+ *    components — the plural form stays stale until unrelated state forces a
+ *    render. Fine when locale changes via full-page navigation; a consumer that
+ *    switches locale client-side should pass the already-formatted/pluralized
+ *    string as the prop instead.
+ * 2. Does not cross shadow boundaries. `el.closest('[lang]')` stops at the host's
+ *    shadow root. A Pine component nested inside another custom element whose
+ *    `lang` sits on that outer host will not see it and falls back to
+ *    `document.documentElement.lang`. Set `lang` on (or above) the Pine element
+ *    in the same tree, or pass a pre-formatted string, when that matters.
+ */
+/** Replace `{token}` placeholders with `vars`; unknown tokens stay literal. */
+export declare function formatMessage(template: string, vars?: I18nVars): string;
+/** Nearest `[lang]` ancestor, then `<html lang>`, then `'en'`. */
+export declare function resolveLocale(el?: Element | null): string;
+/**
+ * Pick the CLDR plural form for `count` in the element's locale (via the
+ * platform `Intl.PluralRules`) and interpolate `{count}`. `forms` come from the
+ * caller — component props, English-defaulted — and fall back to `other`.
+ */
+export declare function pluralize(el: Element | null, count: number, forms: PluralForms, vars?: I18nVars): string;

package/dist/types/i18n/index.d.ts

@@ -0,0 +1,2 @@
+export { formatMessage, pluralize, resolveLocale } from './i18n-format';
+export type { I18nVars, PluralForms } from './i18n-format';