@primereact/mcp 11.0.0 → 11.2.0

package/data/llms/styled/guides/misc/internationalization.md

@@ -0,0 +1,379 @@
+# Internationalization and Localization
+
+Translating component messages and configuring regional settings such as date formats and the first day of the week.
+
+## Overview
+
+Components ship with a set of built-in messages such as filter operator labels, month names and ARIA descriptions. These messages live in a locale registry that is shared across PrimeReact, PrimeVue and PrimeNG through the `@primeuix/locale` package, and are re-exported from `@primereact/core/locale`.
+
+English is registered by default, so no configuration is required until another language is needed.
+
+Setting a language is enough for components to pick it up. No per-component prop is involved. Switching the language below re-renders the calendar with translated month and day names, moves the first day of the week, and updates the button label.
+
+```tsx
+'use client';
+import { ChevronDown } from '@primeicons/react/chevron-down';
+import { ChevronLeft } from '@primeicons/react/chevron-left';
+import { ChevronRight } from '@primeicons/react/chevron-right';
+import { defineLocale, en, Locale, useLocale } from '@primereact/core/locale';
+import { Button } from '@primereact/ui/button';
+import { DatePicker, type DatePickerRootProps, type DatePickerRootValueChangeEvent } from '@primereact/ui/datepicker';
+import { Select, type SelectValueChangeEvent } from '@primereact/ui/select';
+import * as React from 'react';
+
+// Spreading `en` keeps every untranslated key readable instead of resolving to undefined.
+defineLocale('de', {
+    ...en,
+    dayNamesMin: ['So', 'Mo', 'Di', 'Mi', 'Do', 'Fr', 'Sa'],
+    monthNames: ['Januar', 'Februar', 'März', 'April', 'Mai', 'Juni', 'Juli', 'August', 'September', 'Oktober', 'November', 'Dezember'],
+    today: 'Heute',
+    clear: 'Löschen',
+    firstDayOfWeek: 1
+});
+
+defineLocale('es', {
+    ...en,
+    dayNamesMin: ['Do', 'Lu', 'Ma', 'Mi', 'Ju', 'Vi', 'Sá'],
+    monthNames: ['Enero', 'Febrero', 'Marzo', 'Abril', 'Mayo', 'Junio', 'Julio', 'Agosto', 'Septiembre', 'Octubre', 'Noviembre', 'Diciembre'],
+    today: 'Hoy',
+    clear: 'Limpiar',
+    firstDayOfWeek: 1
+});
+
+const languages = [
+    { label: 'English', value: 'en' },
+    { label: 'Deutsch', value: 'de' },
+    { label: 'Español', value: 'es' }
+];
+
+export default function SwitcherDemo() {
+    const [date, setDate] = React.useState<DatePickerRootProps['value'] | null>(null);
+    const { lang, t } = useLocale();
+
+    return (
+        <div className="flex flex-col items-center gap-4">
+            <Select.Root
+                value={lang}
+                onValueChange={(event: SelectValueChangeEvent) => Locale.use(event.value as string)}
+                options={languages}
+                optionLabel="label"
+                optionValue="value"
+                className="w-full md:w-56"
+            >
+                <Select.Trigger>
+                    <Select.Value />
+                    <Select.Indicator>
+                        <ChevronDown />
+                    </Select.Indicator>
+                </Select.Trigger>
+                <Select.Portal>
+                    <Select.Positioner>
+                        <Select.Popup>
+                            <Select.List />
+                        </Select.Popup>
+                    </Select.Positioner>
+                </Select.Portal>
+            </Select.Root>
+
+            <DatePicker.Root value={date} onValueChange={(event: DatePickerRootValueChangeEvent) => setDate(event.value)}>
+                <DatePicker.Body>
+                    <DatePicker.Panel>
+                        <DatePicker.Calendar>
+                            <DatePicker.Header className="bg-transparent!">
+                                <DatePicker.Prev as={Button} iconOnly variant="text" rounded severity="secondary" size="small">
+                                    <ChevronLeft />
+                                </DatePicker.Prev>
+                                <DatePicker.Title>
+                                    <DatePicker.SelectMonth />
+                                    <DatePicker.SelectYear />
+                                    <DatePicker.Decade />
+                                </DatePicker.Title>
+                                <DatePicker.Next as={Button} iconOnly variant="text" rounded severity="secondary" size="small">
+                                    <ChevronRight />
+                                </DatePicker.Next>
+                            </DatePicker.Header>
+                            <DatePicker.Table>
+                                <DatePicker.TableHead />
+                                <DatePicker.TableBody />
+                                <DatePicker.TableBody view="month" />
+                                <DatePicker.TableBody view="year" />
+                            </DatePicker.Table>
+                        </DatePicker.Calendar>
+                    </DatePicker.Panel>
+                </DatePicker.Body>
+            </DatePicker.Root>
+
+            <Button severity="secondary" onClick={() => setDate(null)}>
+                {t('clear')}
+            </Button>
+        </div>
+    );
+}
+```
+
+## Import
+
+```js
+import { $t, $l, defineLocale, updateLocale, useLocale, Locale, LocaleService, en } from '@primereact/core/locale';
+```
+
+## Setting the Language
+
+`Locale.use` selects the active language. Every component reading a message re-renders when it changes, so this works both at startup and later in response to a language switcher.
+
+```js
+import { Locale } from '@primereact/core/locale';
+
+Locale.use('de');
+```
+
+Only `en` is built in, so any other language has to be registered first. See [Adding a Language](#adding-a-language) below.
+
+`PrimeReactProvider` also accepts a `locale` prop, which sets the initial language for the components beneath it.
+
+```jsx
+import { PrimeReactProvider } from '@primereact/core';
+
+<PrimeReactProvider locale="de">
+    <App />
+</PrimeReactProvider>;
+```
+
+## Adding a Language
+
+`defineLocale` registers a new language.
+
+```js
+import { defineLocale, Locale } from '@primereact/core/locale';
+
+defineLocale('es', {
+    clear: 'Limpiar',
+    apply: 'Aplicar',
+    accept: 'Sí',
+    reject: 'No',
+    dayNames: ['domingo', 'lunes', 'martes', 'miércoles', 'jueves', 'viernes', 'sábado'],
+    dayNamesShort: ['dom', 'lun', 'mar', 'mié', 'jue', 'vie', 'sáb'],
+    dayNamesMin: ['D', 'L', 'M', 'X', 'J', 'V', 'S'],
+    monthNames: ['enero', 'febrero', 'marzo', 'abril', 'mayo', 'junio', 'julio', 'agosto', 'septiembre', 'octubre', 'noviembre', 'diciembre'],
+    monthNamesShort: ['ene', 'feb', 'mar', 'abr', 'may', 'jun', 'jul', 'ago', 'sep', 'oct', 'nov', 'dic']
+});
+
+Locale.use('es');
+```
+
+A registered language must be complete. Keys that are left out resolve to `undefined` rather than falling back to English, which renders as an empty label. The practical approach is to spread the built-in English messages and override from there:
+
+```js
+import { defineLocale, en } from '@primereact/core/locale';
+
+defineLocale('es', {
+    ...en,
+    clear: 'Limpiar',
+    apply: 'Aplicar'
+});
+```
+
+The `en` object holds the built-in English messages and is exported for exactly this purpose. Ready-made translations from [PrimeLocale](#ready-made-translations) already cover every key, so spreading is only needed for hand-written translations.
+
+The provider accepts a `locales` map, which registers languages and selects one in a single step. Anything listed here is registered before `locale` is applied.
+
+```jsx
+import { PrimeReactProvider } from '@primereact/core';
+
+<PrimeReactProvider locale="es" locales={{ es: spanishMessages }}>
+    <App />
+</PrimeReactProvider>;
+```
+
+## Updating an Existing Language
+
+`updateLocale` merges new values into a language that is already registered, leaving the remaining keys untouched. It is useful for overriding a handful of labels without redefining a full translation.
+
+```js
+import { updateLocale } from '@primereact/core/locale';
+
+updateLocale('en', {
+    clear: 'Reset',
+    apply: 'Confirm'
+});
+```
+
+If the language does not exist yet, `updateLocale` registers it, behaving like `defineLocale`.
+
+## Reading Messages
+
+### In Components
+
+`useLocale` is the React hook for reading the active locale. It re-renders the calling component when the language changes.
+
+```jsx
+import { Button } from '@primereact/ui/button';
+import { useLocale } from '@primereact/core/locale';
+
+function ClearFilterButton({ onClear }) {
+    const { t } = useLocale();
+
+    return (
+        <Button severity="secondary" onClick={onClear}>
+            {t('clear')}
+        </Button>
+    );
+}
+```
+
+| Field      | Description                                   |
+| ---------- | --------------------------------------------- |
+| `lang`     | Active language code, such as `en` or `de`.   |
+| `messages` | Full message object of the active language.   |
+| `t`        | Translates a key against the active language. |
+
+Re-rendering on a language change relies on the context published by `PrimeReactProvider`, which applications normally have at their root. A component rendered outside any provider still reads the correct messages on first render, but will not update when the language changes later.
+
+### Outside Components
+
+`$t` performs the same lookup without a React context, which suits utilities, event handlers and module-level code.
+
+```js
+import { $t } from '@primereact/core/locale';
+
+$t('clear'); // 'Clear'
+```
+
+Nested keys use dot notation.
+
+```js
+$t('aria.selectRow'); // 'Row Selected'
+```
+
+Messages containing placeholders accept replacement values. Positional placeholders such as `{0}` are filled from the argument order, while named ones are filled from an object.
+
+```js
+$t('searchMessage', 5); // '5 results are available'
+$t('selectionMessage', 3); // '3 items selected'
+$t('aria.stars', { star: 4 }); // '4 stars'
+```
+
+## Reacting to Language Changes
+
+Language changes emit a `locale:change` event. Components handle this automatically through `useLocale`; the event is only needed for code living outside React, such as syncing a third-party library.
+
+```js
+import { LocaleService } from '@primereact/core/locale';
+
+const onChange = ({ lang }) => console.log('Language is now', lang);
+
+LocaleService.on('locale:change', onChange);
+
+// remove the listener when it is no longer needed
+LocaleService.off('locale:change', onChange);
+```
+
+## Inspecting the Registry
+
+`$l` returns a facade over the registry, which helps when building a language switcher.
+
+```js
+import { $l } from '@primereact/core/locale';
+
+$l().langs; // ['en', 'es']
+$l().get('es'); // message object of the Spanish locale
+```
+
+## Message Keys
+
+These components read their labels from the active language:
+
+| Component  | Keys                                                                                                                                                    |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| DatePicker | `dayNames`, `dayNamesShort`, `dayNamesMin`, `monthNames`, `monthNamesShort`, `today`, `weekHeader`, `clear`, `am`, `pm`, `firstDayOfWeek`, `dateFormat` |
+| FileUpload | `fileSizeTypes`                                                                                                                                         |
+| Paginator  | `aria.firstPageLabel`, `aria.prevPageLabel`, `aria.nextPageLabel`, `aria.lastPageLabel`, `aria.pageLabel`                                               |
+| Sidebar    | `aria.toggleSidebar`                                                                                                                                    |
+
+The registry holds a larger set covering filter operators, password strength labels, empty-state messages and the remaining `aria` labels. Those are reserved for components that do not consume them yet, so translating them has no visible effect today.
+
+Not every entry is a string. `firstDayOfWeek` is a number, `showMonthAfterYear` is a boolean, and `dayNames`, `monthNames` and `fileSizeTypes` are arrays. `searchMessage` and similar entries carry a `{0}` placeholder.
+
+The full set with default English values is exported as `en`, which can also be inspected at runtime:
+
+```js
+import { en } from '@primereact/core/locale';
+
+Object.keys(en); // every top-level key
+```
+
+## Ready-Made Translations
+
+Writing a translation from scratch is rarely necessary. The community maintained [PrimeLocale](https://github.com/primefaces/primelocale) repository publishes complete translations for 70+ languages, shared across all Prime libraries. Each file covers every built-in message key, so nothing is left resolving to `undefined`.
+
+### Copying a File
+
+Grab the JSON file for the desired language from the repository, for example `es.json`, and place it in the project.
+
+Each file wraps its messages in a single key named after the language:
+
+```json
+{
+    "es": {
+        "clear": "Limpiar",
+        "apply": "Aplicar",
+        "aria": { "selectRow": "Seleccionar fila" }
+    }
+}
+```
+
+That wrapper has to be unwrapped before registering, otherwise every lookup resolves to `undefined`:
+
+```js
+import { defineLocale, Locale } from '@primereact/core/locale';
+import es from './locales/es.json';
+
+defineLocale('es', es.es);
+Locale.use('es');
+```
+
+The same unwrapping applies when the language is registered through the provider:
+
+```jsx
+import { PrimeReactProvider } from '@primereact/core';
+import es from './locales/es.json';
+
+<PrimeReactProvider locale="es" locales={{ es: es.es }}>
+    <App />
+</PrimeReactProvider>;
+```
+
+### Installing the Package
+
+The translations are also published to npm, which avoids maintaining copies by hand.
+
+```bash
+npm install primelocale
+```
+
+```js
+import { defineLocale, Locale } from '@primereact/core/locale';
+import { es } from 'primelocale/js/es.js';
+
+defineLocale('es', es);
+Locale.use('es');
+```
+
+The package entry points export the messages directly, so no unwrapping is needed there.
+
+Regional variants are named with an underscore in the package and a hyphen in the JSON files. Brazilian Portuguese is `primelocale/js/pt_BR.js` when imported and `pt-BR.json` when copied.
+
+### Adjusting a Translation
+
+A ready-made translation can be tuned without editing the file, by layering overrides on top of it:
+
+```js
+defineLocale('es', es.es);
+updateLocale('es', { clear: 'Borrar' });
+```
+
+Contributions of new languages and corrections are welcome in the PrimeLocale repository, and benefit every Prime library at once.
+
+## Coming from v10
+
+The locale helpers from `primereact/api` were replaced. The [migration guide](/docs/styled/guides/migration/updating-to-v11) maps each one to its replacement.

package/data/llms/styled/guides/theming/tailwind.md

@@ -48,6 +48,31 @@ In the CSS file that contains the tailwindcss import, add the `tailwindcss-prime
 @import 'tailwindcss-primeui';
 ```
 
+### Cascade layer
+
+PrimeReact resets the browser defaults on the native elements it renders (preflight, see the [configuration guide](/docs/styled/guides/configuration)), and those rules live in `primeui.base`, a cascade layer nested under `primeui`. A CSS layer is ordered where its name is first declared, not where its rules are written, so when `tailwindcss` declares its layers first, `primeui` ends up after them and the reset wins over utility classes.
+
+This only shows up in server-rendered apps, and only before hydration: PrimeReact injects the layer declaration at runtime, which lands after the application's own CSS on the first server-rendered response. Utility classes meant to override the reset lose until the client takes over, so the first paint is visibly wrong and corrects itself once React hydrates.
+
+Fix the order by declaring the layer above the `tailwindcss` import:
+
+```css
+@layer primeui;
+
+@import 'tailwindcss';
+@import 'tailwindcss-primeui';
+```
+
+Declaring `primeui` is enough on its own: `primeui.base`, where the reset lives, is nested inside it, and a nested layer's order is fixed by its parent's. Declaring it after the `tailwindcss` import does nothing, since the order is already fixed by then. This applies to any framework that declares its own layers, not just Tailwind.
+
+An application with `theme.options.cssLayer` enabled has already declared this layer: that option wraps PrimeReact's component styles, variables and global style in a layer named `primeui` by default, or in whatever name is passed to it (`{ name: 'myui' }` produces `myui`), and `@layer primeui;` covers the reset and that layer with the same line.
+
+Where Tailwind's own preflight is already in use, or another reset such as normalize.css or Bootstrap's reboot, turn off PrimeReact's instead of maintaining two resets:
+
+```tsx
+<PrimeReactProvider preflight={false}>
+```
+
 ### Tailwind v3
 
 Use the plugins option in your Tailwind config file to configure the plugin.

package/data/llms/tailwind/components/button/api.json

@@ -37,19 +37,19 @@
             },
             {
               "name": "style",
-              "type": "CSSProperties | ((instance?: ButtonInstance) => CSSProperties)",
+              "type": "CSSProperties | ((instance?: ButtonInstance) => undefined | CSSProperties)",
               "default": "",
               "description": "The style to apply to the component."
             },
             {
               "name": "className",
-              "type": "string | ((instance?: ButtonInstance) => string)",
+              "type": "string | ((instance?: ButtonInstance) => undefined | string)",
               "default": "",
               "description": "The class name to apply to the component."
             },
             {
               "name": "as",
-              "type": "string | number | bigint | boolean | ComponentClass<any, any> | FunctionComponent<any> | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode, any, any> | ReactPortal | Promise<AwaitedReactNode>",
+              "type": "null | string | number | bigint | boolean | ComponentClass<any, any> | FunctionComponent<any> | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode, any, any> | ReactPortal | Promise<AwaitedReactNode>",
               "default": "",
               "description": "The component type to render."
             },
@@ -128,31 +128,31 @@
             {
               "name": "plain",
               "type": "boolean",
-              "default": "",
+              "default": "false",
               "description": "Whether to show the Button with a plain style."
             },
             {
               "name": "rounded",
               "type": "boolean",
-              "default": "",
+              "default": "false",
               "description": "Whether to show the Button with a rounded style."
             },
             {
               "name": "raised",
               "type": "boolean",
-              "default": "",
+              "default": "false",
               "description": "Whether to show the Button with a raised style."
             },
             {
               "name": "iconOnly",
               "type": "boolean",
-              "default": "",
+              "default": "false",
               "description": "Whether to show the Button with a borderless style."
             },
             {
               "name": "fluid",
               "type": "boolean",
-              "default": "",
+              "default": "false",
               "description": "Whether to show the Button with a fluid width."
             },
             {