@konce-pt/react 0.9.1 → 0.11.0

package/dist/public-api.js

@@ -71,7 +71,7 @@ export { KptOverlay } from "./internal/overlay.js";
 export { KptButtonGroup } from "./button-group/button-group.js";
 export { KptSelect } from "./select/select.js";
 export { KptFormField } from "./form-field/form-field.js";
-export { useKptFormFieldContext, useKptFormFieldFilled } from "./form-field/form-field-context.js";
+export { useKptFieldA11y, useKptFormFieldContext, useKptFormFieldFilled } from "./form-field/form-field-context.js";
 export { KptCheckbox } from "./checkbox/checkbox.js";
 export { KptAutocomplete } from "./autocomplete/autocomplete.js";
 export { KptListbox } from "./listbox/listbox.js";

package/dist/radio-group/llms.txt

@@ -31,6 +31,17 @@ interfere.
     <KptRadioGroup options={plans} value={plan} onValueChange={setPlan} />
     <KptRadioGroup name="plan" options={plans} defaultValue="pro" />
 
+## Screen reader and keyboard
+`orientation`: 'vertical' (default) | 'horizontal' — options in a column or in a wrapping row; also
+sets `aria-orientation`.
+
+## Label and description
+`id` goes to the focusable element, not the host; without one it comes from `KptFormField` or is
+generated. A `div` with a role is not named by `label[for]`, so inside `KptFormField` it gets
+`aria-labelledby` pointing at the wrapper's label (unless `ariaLabel` is set), and the hint or error
+is added to `aria-describedby`. New: `id`, `ariaLabel` and `required` (→ `aria-required`) on the
+`radiogroup`.
+
 ## Tokens
 `--kpt-color-primary` (the checked dot), `--kpt-form-field-border`,
 `--kpt-form-field-border-error`.

package/dist/radio-group/radio-group.d.ts

@@ -7,6 +7,14 @@ export interface KptRadioGroupProps<T> extends Omit<ComponentPropsWithRef<'div'>
     onValueChange?: (value: T) => void;
     /** Nazwa grupy w formularzu; pominięta = generowana. */
     name?: string;
+    /** Id elementu fokusowalnego (nie hosta); bez niego generowane, w `KptFormField` — z wrappera. */
+    id?: string;
+    /** Nazwa dostępna, gdy kontrolki nie opisuje etykieta (`<label for>` albo `KptFormField`). */
+    ariaLabel?: string | null;
+    /** Oznacza grupę jako wymaganą atrybutem `aria-required`. */
+    required?: boolean;
+    /** Układ opcji: pod sobą (domyślnie) albo w rzędzie, z zawijaniem. */
+    orientation?: 'vertical' | 'horizontal';
     disabled?: boolean;
     invalid?: boolean;
     touched?: boolean;
@@ -21,4 +29,4 @@ export interface KptRadioGroupProps<T> extends Omit<ComponentPropsWithRef<'div'>
  * @example
  * <KptRadioGroup options={plans} value={plan} onValueChange={setPlan} />
  */
-export declare function KptRadioGroup<T>({ options, value, defaultValue, onValueChange, name, disabled, invalid, touched, onTouch, className, ...rest }: Readonly<KptRadioGroupProps<T>>): import("react").JSX.Element;
+export declare function KptRadioGroup<T>({ options, value, defaultValue, onValueChange, name, id, ariaLabel, required, orientation, disabled, invalid, touched, onTouch, className, ...rest }: Readonly<KptRadioGroupProps<T>>): import("react").JSX.Element;

package/dist/radio-group/radio-group.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cn } from "../internal/cn.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
 import { useKptId } from "../internal/use-id.js";
+import { useKptFieldA11y } from "../form-field/form-field-context.js";
 /**
  * Grupa przycisków opcji (radio). Opcje przez `options`.
  *
@@ -11,7 +12,9 @@ import { useKptId } from "../internal/use-id.js";
  * @example
  * <KptRadioGroup options={plans} value={plan} onValueChange={setPlan} />
  */
-export function KptRadioGroup({ options = [], value, defaultValue, onValueChange, name, disabled = false, invalid = false, touched, onTouch, className, ...rest }) {
+export function KptRadioGroup({ options = [], value, defaultValue, onValueChange, name, id, ariaLabel = null, required = false, orientation = 'vertical', disabled = false, invalid = false, touched, onTouch, className, ...rest }) {
+    /** Grupa nie dostaje nazwy z `label[for]` — stąd `aria-labelledby` na etykietę wrappera. */
+    const field = useKptFieldA11y(id, 'kpt-radio-group');
     const groupName = useKptId(name, 'kpt-radio');
     const [current, setCurrent] = useControllableState({
         value,
@@ -19,5 +22,5 @@ export function KptRadioGroup({ options = [], value, defaultValue, onValueChange
         onChange: onValueChange,
     });
     const showInvalid = invalid && (touched ?? true);
-    return (_jsx("div", { className: cn('kpt-radio-group-host', className), ...rest, children: _jsx("div", { className: "kpt-radio-group", role: "radiogroup", "aria-invalid": showInvalid || undefined, children: options.map((option) => (_jsxs("label", { className: cn('kpt-radio', (disabled || option.disabled) && 'kpt-radio--disabled'), children: [_jsx("input", { type: "radio", className: "kpt-radio__input", name: groupName, checked: option.value === current, disabled: disabled || option.disabled, onChange: () => setCurrent(option.value), onBlur: () => onTouch?.() }), _jsx("span", { className: "kpt-radio__dot", "aria-hidden": "true" }), _jsx("span", { className: "kpt-radio__label", children: option.label })] }, String(option.value)))) }) }));
+    return (_jsx("div", { className: cn('kpt-radio-group-host', className), ...rest, children: _jsx("div", { className: cn('kpt-radio-group', orientation === 'horizontal' && 'kpt-radio-group--horizontal'), role: "radiogroup", "aria-orientation": orientation, "aria-invalid": showInvalid || undefined, id: field.id, "aria-label": ariaLabel ?? undefined, "aria-labelledby": ariaLabel ? undefined : field.labelledBy, "aria-describedby": field.describedBy, "aria-required": required || undefined, children: options.map((option) => (_jsxs("label", { className: cn('kpt-radio', (disabled || option.disabled) && 'kpt-radio--disabled'), children: [_jsx("input", { type: "radio", className: "kpt-radio__input", name: groupName, checked: option.value === current, disabled: disabled || option.disabled, onChange: () => setCurrent(option.value), onBlur: () => onTouch?.() }), _jsx("span", { className: "kpt-radio__dot", "aria-hidden": "true" }), _jsx("span", { className: "kpt-radio__label", children: option.label })] }, String(option.value)))) }) }));
 }

package/dist/rating/llms.txt

@@ -5,8 +5,8 @@ Import: `import { KptRating } from '@konce-pt/react';`
 
 ## DOM
     <div class="kpt-rating-host">
-      <div class="kpt-rating" role="slider" aria-valuenow="3" aria-valuemax="5">
-        <button class="kpt-rating__star is-filled" aria-label="1 of 5">…</button>
+      <div class="kpt-rating" role="radiogroup" aria-label="…">
+        <button class="kpt-rating__star is-filled" role="radio" aria-checked="false" tabindex="-1" aria-label="1 of 5">…</button>
         …count buttons…
       </div>
     </div>
@@ -14,9 +14,11 @@ Import: `import { KptRating } from '@konce-pt/react';`
 ## Props
 - `value` / `defaultValue` / `onValueChange` — the score as a number, `0` means unrated
 - `count`: number (default 5)
+- `allowHalf`: boolean — half stars, the value goes in steps of 0.5
 - `readOnly`: boolean — display only, no clicking and no hover preview
 - `disabled`: boolean
-- `onTouch()` — fired together with a pick
+- `onTouch()` — when focus leaves the group
+- `id`, `ariaLabel`, `required`, `invalid`, `touched`
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## Clicking a lit star clears the score
@@ -35,9 +37,20 @@ per instance with the `locale` / `dictionary` props.
     <KptRating value={score} onValueChange={setScore} count={5} />
     <KptRating value={4} readOnly />
 
+## Half stars
+`allowHalf` splits every star into two halves, each its own `role="radio"` ("3.5 of 5" — the number
+follows the page language, PL "3,5 z 5"), so the group keeps the radio pattern: clicking the left half
+gives x.5, and the arrows step by 0.5. Read-only stars show the value rounded to a half (4.3 → four
+and a half stars) while the name carries the exact score ("4.3 of 5"), so an average can be shown
+as it is.
+
 ## Tokens
 Lit stars `--kpt-color-warning`, empty ones `--kpt-color-border-strong`.
 
 ## Accessibility
-`role="slider"` with `aria-valuenow` / `aria-valuemax`; every star is a real `<button>`, so the
-row is reachable with Tab and each value can be picked from the keyboard.
+`role="radiogroup"` named by `ariaLabel` or the `KptFormField` label; each star is
+`role="radio"` with `aria-checked`, labelled from `rating.star` (`{value}`, `{max}`) — EN `1 of 5`,
+PL `1 z 5`. One Tab stop: `→`/`↑` raise the score by one, `←`/`↓` lower it (mirrored in RTL),
+`Home`/`End` set the extremes, `Delete`/`Backspace` clear it; clicking the chosen star also clears it.
+`readOnly` renders `role="img"` named "4 of 5" with no buttons, so a screen reader does not announce
+a row of disabled controls. `touch` fires when focus leaves the group.

package/dist/rating/rating.d.ts

@@ -6,17 +6,35 @@ export interface KptRatingProps extends Omit<ComponentPropsWithRef<'div'>, 'onCh
     onValueChange?: (value: number) => void;
     /** Liczba gwiazdek. */
     count?: number;
+    /** Połówki gwiazdek: wartość co 0,5, każda połówka to osobne `radio`. */
+    allowHalf?: boolean;
     /** Ocena tylko do odczytu — bez klikania i bez podglądu pod kursorem. */
     readOnly?: boolean;
+    /** Id grupy (nie hosta); bez niego generowane, w `KptFormField` — z wrappera. */
+    id?: string;
+    /** Nazwa dostępna grupy, gdy nie opisuje jej etykieta (`KptFormField`). */
+    ariaLabel?: string | null;
+    /** Oznacza ocenę jako wymaganą atrybutem `aria-required`. */
+    required?: boolean;
     disabled?: boolean;
+    invalid?: boolean;
+    touched?: boolean;
     onTouch?: () => void;
 }
 /**
  * Ocena gwiazdkami. Kliknięcie zapalonej gwiazdki zeruje ocenę, więc wystawioną można cofnąć
  * bez osobnego przycisku „wyczyść".
  *
+ * Do edycji to grupa radiowa (`role="radiogroup"`, gwiazdki jako `role="radio"`): jeden przystanek
+ * Tab, strzałki zmieniają ocenę o krok (w RTL odwrócone w poziomie), `Home`/`End` ustawiają
+ * skrajne, `Delete`/`Backspace` zeruje. Z `allowHalf` każda gwiazdka ma dwie połówki — dwa osobne
+ * `radio` („3,5 z 5”), a krok strzałek to 0,5. Tylko do odczytu (`readOnly`) to obrazek z nazwą
+ * „4,3 z 5” — bez przycisków, które czytnik ogłaszałby jako wyłączone; gwiazdki pokazują wartość
+ * zaokrągloną do połówki.
+ *
  * @example
- * <KptRating value={score} onValueChange={setScore} count={5} />
- * <KptRating value={4} readOnly />
+ * <KptRating value={score} onValueChange={setScore} count={5} ariaLabel="Ocena" />
+ * <KptRating value={score} onValueChange={setScore} allowHalf ariaLabel="Ocena" />
+ * <KptRating value={4.3} readOnly />
  */
-export declare function KptRating({ value, defaultValue, onValueChange, count, readOnly, disabled, onTouch, locale, dictionary, className, ...rest }: Readonly<KptRatingProps>): import("react").JSX.Element;
+export declare function KptRating({ value, defaultValue, onValueChange, count, allowHalf, readOnly, id, ariaLabel, required, disabled, invalid, touched, onTouch, locale, dictionary, className, ...rest }: Readonly<KptRatingProps>): import("react").JSX.Element;

package/dist/rating/rating.js

@@ -1,30 +1,105 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { useState } from 'react';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
 import { cn } from "../internal/cn.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
+import { useKptFieldA11y } from "../form-field/form-field-context.js";
 import { KptIcon } from "../icon/icon.js";
+const fillOf = (star, shown) => shown >= star ? 'full' : shown >= star - 0.5 ? 'half' : 'empty';
 /**
  * Ocena gwiazdkami. Kliknięcie zapalonej gwiazdki zeruje ocenę, więc wystawioną można cofnąć
  * bez osobnego przycisku „wyczyść".
  *
+ * Do edycji to grupa radiowa (`role="radiogroup"`, gwiazdki jako `role="radio"`): jeden przystanek
+ * Tab, strzałki zmieniają ocenę o krok (w RTL odwrócone w poziomie), `Home`/`End` ustawiają
+ * skrajne, `Delete`/`Backspace` zeruje. Z `allowHalf` każda gwiazdka ma dwie połówki — dwa osobne
+ * `radio` („3,5 z 5”), a krok strzałek to 0,5. Tylko do odczytu (`readOnly`) to obrazek z nazwą
+ * „4,3 z 5” — bez przycisków, które czytnik ogłaszałby jako wyłączone; gwiazdki pokazują wartość
+ * zaokrągloną do połówki.
+ *
  * @example
- * <KptRating value={score} onValueChange={setScore} count={5} />
- * <KptRating value={4} readOnly />
+ * <KptRating value={score} onValueChange={setScore} count={5} ariaLabel="Ocena" />
+ * <KptRating value={score} onValueChange={setScore} allowHalf ariaLabel="Ocena" />
+ * <KptRating value={4.3} readOnly />
  */
-export function KptRating({ value, defaultValue = 0, onValueChange, count = 5, readOnly = false, disabled = false, onTouch, locale, dictionary, className, ...rest }) {
-    const { t } = useKptMessages({ locale, dictionary });
+export function KptRating({ value, defaultValue = 0, onValueChange, count = 5, allowHalf = false, readOnly = false, id, ariaLabel = null, required = false, disabled = false, invalid = false, touched, onTouch, locale, dictionary, className, ...rest }) {
+    const { t, locale: activeLocale } = useKptMessages({ locale, dictionary });
+    const field = useKptFieldA11y(id, 'kpt-rating');
     const [current, setCurrent] = useControllableState({ value, defaultValue, onChange: onValueChange });
     const [hover, setHover] = useState(0);
-    const locked = readOnly || disabled;
+    const groupRef = useRef(null);
+    /** Prośba o fokus na przystanek Tab po najbliższym renderze (zmiana oceny klawiszem). */
+    const wantFocus = useRef(false);
+    const showInvalid = invalid && (touched ?? true);
+    const stars = Array.from({ length: count }, (_, index) => index + 1);
+    const step = allowHalf ? 0.5 : 1;
     // Podgląd pod kursorem wygrywa z oceną, ale tylko dopóki kursor jest nad gwiazdkami —
     // po `mouseleave` wraca 0 i zapalona zostaje sama wartość.
     const shown = hover || current;
-    const pick = (star) => {
-        if (locked)
+    /** Przystanek Tab: wybrana wartość, a bez oceny — pierwsza możliwa. */
+    const tabStop = current >= step && current <= count ? current : step;
+    /** Liczba w zapisie języka strony („3,5” po polsku). */
+    const numberFormat = new Intl.NumberFormat(activeLocale, { maximumFractionDigits: 2 });
+    const starLabel = (score) => t('rating.star', { value: numberFormat.format(score), max: count });
+    useEffect(() => {
+        if (!wantFocus.current)
+            return;
+        wantFocus.current = false;
+        groupRef.current?.querySelector(`[data-value="${tabStop}"]`)?.focus();
+    });
+    const starVisual = (star, fill, children, hidden = false) => (_jsxs("span", { className: "kpt-rating__star", "data-fill": fill, "aria-hidden": hidden || undefined, children: [_jsx(KptIcon, { name: "star" }), _jsx("span", { className: "kpt-rating__fill", "aria-hidden": "true", children: _jsx(KptIcon, { name: "star" }) }), children] }, star));
+    if (readOnly) {
+        const score = starLabel(current);
+        // Gwiazdki pokazują wartość zaokrągloną do połówki (4,3 → 4,5), nazwa — dokładną.
+        const display = Math.round(current * 2) / 2;
+        return (_jsx("div", { className: cn('kpt-rating-host', className), ...rest, children: _jsx("div", { className: "kpt-rating kpt-rating--readonly", role: "img", id: field.id, "aria-label": ariaLabel ? `${ariaLabel}: ${score}` : score, "aria-describedby": field.describedBy, children: stars.map((star) => starVisual(star, fillOf(star, display), null, true)) }) }));
+    }
+    const pick = (score) => {
+        if (disabled)
+            return;
+        setCurrent(current === score ? 0 : score);
+    };
+    const onKeyDown = (event) => {
+        if (disabled)
+            return;
+        const rtl = getComputedStyle(event.currentTarget).direction === 'rtl';
+        const forward = rtl ? 'ArrowLeft' : 'ArrowRight';
+        const back = rtl ? 'ArrowRight' : 'ArrowLeft';
+        let next = null;
+        if (event.key === forward || event.key === 'ArrowUp')
+            next = Math.min(count, Math.max(step, current + step));
+        else if (event.key === back || event.key === 'ArrowDown')
+            next = Math.max(step, current - step);
+        else if (event.key === 'Home')
+            next = step;
+        else if (event.key === 'End')
+            next = count;
+        else if (event.key === 'Delete' || event.key === 'Backspace')
+            next = 0;
+        else if (event.key === ' ' || event.key === 'Enter') {
+            // Spacja na gwiazdce wybiera ją (jak radio); ponowna nie zeruje — od tego jest Delete.
+            const score = Number(event.target.dataset['value']);
+            if (score)
+                next = score;
+        }
+        if (next === null)
             return;
-        setCurrent(current === star ? 0 : star);
-        onTouch?.();
+        event.preventDefault();
+        setCurrent(next);
+        wantFocus.current = true;
+    };
+    /** „Dotknięcie” dopiero przy wyjściu fokusu z całej grupy, nie przy przejściu między gwiazdkami. */
+    const onBlur = (event) => {
+        const next = event.relatedTarget;
+        if (!next || !event.currentTarget.contains(next))
+            onTouch?.();
     };
-    return (_jsx("div", { className: cn('kpt-rating-host', className), ...rest, children: _jsx("div", { className: "kpt-rating", role: "slider", "aria-valuenow": current, "aria-valuemax": count, children: Array.from({ length: count }, (_, index) => index + 1).map((star) => (_jsx("button", { type: "button", className: cn('kpt-rating__star', star <= shown && 'is-filled'), disabled: locked, onClick: () => pick(star), onMouseEnter: () => setHover(star), onMouseLeave: () => setHover(0), "aria-label": t('rating.star', { value: star, max: count }), children: _jsx(KptIcon, { name: "star" }) }, star))) }) }));
+    /** Pola wyboru jednej gwiazdki: całość albo — z `allowHalf` — dwie połówki. */
+    const optionsOf = (star) => allowHalf
+        ? [
+            { score: star - 0.5, part: 'start' },
+            { score: star, part: 'end' },
+        ]
+        : [{ score: star, part: 'full' }];
+    return (_jsx("div", { className: cn('kpt-rating-host', className), ...rest, children: _jsx("div", { ref: groupRef, className: cn('kpt-rating', disabled && 'kpt-rating--disabled'), role: "radiogroup", id: field.id, "aria-label": ariaLabel ?? undefined, "aria-labelledby": ariaLabel ? undefined : field.labelledBy, "aria-describedby": field.describedBy, "aria-required": required || undefined, "aria-invalid": showInvalid || undefined, "aria-disabled": disabled || undefined, onKeyDown: onKeyDown, onBlur: onBlur, onMouseLeave: () => setHover(0), children: stars.map((star) => starVisual(star, fillOf(star, shown), optionsOf(star).map((option) => (_jsx("button", { type: "button", role: "radio", className: cn('kpt-rating__hit', `kpt-rating__hit--${option.part}`), "aria-checked": option.score === current, tabIndex: !disabled && option.score === tabStop ? 0 : -1, "aria-disabled": disabled || undefined, "data-value": option.score, "aria-label": starLabel(option.score), onClick: () => pick(option.score), onMouseEnter: () => !disabled && setHover(option.score) }, option.part))))) }) }));
 }

package/dist/rich-text/llms.txt

@@ -45,6 +45,11 @@ only when the operation actually changed something — otherwise Tab stays nativ
 never becomes a keyboard trap (WCAG 2.1.2). In a table cell Tab moves to the next cell; a list
 inside the cell takes precedence.
 
+## The toolbar is one Tab stop
+The toolbar is a named `role="toolbar"` ("Formatting", `richText.toolbar`) with a roving tabindex:
+`←`/`→` (mirrored in RTL) and `Home`/`End` move between tools, skipping disabled ones; the stop
+remembers the last tool, so Tab from the toolbar goes straight to the editor.
+
 ## Tables
 Insert from an 8×8 grid popover. Dragging across cells makes a rectangular selection that grows
 until it fully covers merged cells on its edges. Right-click opens the menu: insert and delete rows
@@ -69,3 +74,18 @@ Every label comes from the `richText` namespace, including `richText.menu.*` and
 Formatting goes through `document.execCommand`. The API is formally deprecated, but it is the only
 route into the browser's native undo stack (Ctrl+Z); replacing it would mean writing our own
 history, that is, a different editor.
+
+## Screen reader and keyboard
+`link` opens a small dialog instead of the browser's `prompt()`: a labelled URL field (prefilled
+with the current link), `Enter` inserts, `Escape` returns to the text with the selection restored.
+The table context menu is a `role="menu"` of `menuitem`s: it also opens from the keyboard (the menu
+key or `Shift+F10` in a cell), the arrows and `Home`/`End` move, `Escape`/`Tab` close it, and focus
+goes back to the cell. Colour swatches are named ("Dark grey", `richText.swatches.*`) instead of
+their hex codes. The table size grid is still mouse-only.
+
+## Label and description
+`id` goes to the focusable element, not the host; without one it comes from `KptFormField` or is
+generated. A `div` with a role is not named by `label[for]`, so inside `KptFormField` it gets
+`aria-labelledby` pointing at the wrapper's label (unless `ariaLabel` is set), and the hint or error
+is added to `aria-describedby`. New: `id`, `ariaLabel` and `required` (→ `aria-required`) on the
+`role="textbox"` area.

package/dist/rich-text/rich-text.d.ts

@@ -13,6 +13,12 @@ export interface KptRichTextProps extends Omit<ComponentPropsWithRef<'div'>, 'on
     placeholder?: string;
     /** Maksymalna głębokość zagnieżdżenia list (Tab, „Dodaj wcięcie"). */
     maxListLevel?: number;
+    /** Id elementu fokusowalnego (nie hosta); bez niego generowane, w `KptFormField` — z wrappera. */
+    id?: string;
+    /** Nazwa dostępna, gdy kontrolki nie opisuje etykieta (`<label for>` albo `KptFormField`). */
+    ariaLabel?: string | null;
+    /** Oznacza pole jako wymagane atrybutem `aria-required`. */
+    required?: boolean;
     disabled?: boolean;
     invalid?: boolean;
     touched?: boolean;
@@ -35,4 +41,4 @@ export interface KptRichTextProps extends Omit<ComponentPropsWithRef<'div'>, 'on
  * <KptRichText value={html} onValueChange={setHtml} />
  * <KptRichText value={html} onValueChange={setHtml} toolbar={[['bold', 'italic'], ['link']]} />
  */
-export declare function KptRichText({ value, defaultValue, onValueChange, toolbar, placeholder, maxListLevel, disabled, invalid, touched, onTouch, mentions, mentionLimit, onMention, locale, dictionary, className, ...rest }: Readonly<KptRichTextProps>): import("react").JSX.Element;
+export declare function KptRichText({ value, defaultValue, onValueChange, toolbar, placeholder, maxListLevel, id, ariaLabel, required, disabled, invalid, touched, onTouch, mentions, mentionLimit, onMention, locale, dictionary, className, ...rest }: Readonly<KptRichTextProps>): import("react").JSX.Element;