prime-ui-kit 0.9.0 → 0.9.2

package/dist/components/select/selectContext.d.ts

@@ -0,0 +1,61 @@
+import type * as React from "react";
+import { type Store } from "@/internal/listbox";
+import type { ControlSize } from "@/internal/states";
+export type SelectLabels = {
+    /** Placeholder and accessible name of the search field (`Select.Content searchable`). */
+    search: string;
+    /** Empty state: no items or nothing matches. */
+    empty: string;
+    /** Second line of the empty state while searching; `""` hides it. */
+    emptyHint: string;
+    /** Status row while `loading`. */
+    loading: string;
+    /** Tooltip of the clear segment (`clearable`). */
+    clear: string;
+    /** Muted marker after the label when `optional`. */
+    optional: string;
+};
+export declare const normalize: (text: string) => string;
+/**
+ * The items of a Select: their labels (shown in the trigger; kept after an item unmounts, so the
+ * label does not flicker while the list moves between the closed registry and the open panel)
+ * and the mounted ones with their search text (the empty state). `version` changes on every
+ * (un)registration.
+ */
+export type ItemRegistry = {
+    version: Store<number>;
+    labelOf: (value: string) => string;
+    /** Registers a mounted item; returns the unregistration. */
+    register: (value: string, label: string, haystack: string) => () => void;
+    /** Some mounted item matches the normalized query. */
+    anyMatch: (query: string) => boolean;
+};
+export declare function createItemRegistry(): ItemRegistry;
+export type SelectContextValue = {
+    size: ControlSize;
+    invalid: boolean;
+    focusRing: boolean;
+    required: boolean;
+    disabled: boolean;
+    placeholder: string | undefined;
+    multiple: boolean;
+    /** Selected values: one or none in single mode. */
+    selected: string[];
+    registry: ItemRegistry;
+    pick: (value: string) => void;
+    clear: () => void;
+    clearable: boolean;
+    loading: boolean;
+    isOpen: boolean;
+    setOpen: (open: boolean) => void;
+    /** The highlighted option; items subscribe to their own slice of it. */
+    highlight: Store<string | undefined>;
+    query: string;
+    setQuery: (query: string) => void;
+    triggerId: string;
+    listboxId: string;
+    describedBy: string | undefined;
+    triggerRef: React.RefObject<HTMLButtonElement | null>;
+    labels: SelectLabels;
+};
+export declare const SelectProvider: React.Provider<SelectContextValue | null>, useSelectContext: () => SelectContextValue;

package/dist/components/skeleton/Skeleton.d.ts

@@ -0,0 +1,22 @@
+import type * as React from "react";
+import type { ControlSize } from "@/internal/states";
+/**
+ * What the placeholder stands for: `text` — lines of the tier's text; `control` — a field or button
+ * of the tier; `circle` — an avatar of the tier; `block` — any box (image, chart, card), sized by
+ * its container or `className`.
+ */
+export type SkeletonShape = "text" | "control" | "circle" | "block";
+export type SkeletonProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> & {
+    /** Default `text`. */
+    shape?: SkeletonShape;
+    /** Tier of the text line, control height or avatar size. Default: the host tier, else `m`. */
+    size?: ControlSize;
+    /** `text` only: number of lines; the last of several is shorter. Default 1. */
+    lines?: number;
+    ref?: React.Ref<HTMLSpanElement>;
+};
+/**
+ * A placeholder in the shape of the content that is loading, so the layout is already in place
+ * when the data arrives. Decorative (`aria-hidden`): the loading region carries `aria-busy`.
+ */
+export declare function Skeleton({ shape, size: sizeProp, lines, className, ...rest }: SkeletonProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/slider/Slider.d.ts

@@ -1,29 +1,37 @@
-import * as React from "react";
-import type { ControlSize } from "@/internal/states";
-export type SliderRootProps = {
+import { type FieldFrameProps, type FieldRootDomProps } from "@/internal/FieldFrame";
+import type { ControlSize, Tone } from "@/internal/states";
+export type SliderLabels = {
+    /** Muted marker after the label when `optional`. */
+    optional: string;
+};
+export type SliderProps = FieldRootDomProps & Omit<FieldFrameProps, "focusRing"> & {
     value?: number;
     defaultValue?: number;
+    onValueChange?: (value: number) => void;
     min?: number;
     max?: number;
     step?: number;
     disabled?: boolean;
-    onValueChange?: (value: number) => void;
-    /** Visible label linked to the range input. Without it, set `aria-label`. */
-    label?: React.ReactNode;
+    /** Invalid state: `aria-invalid` on the range input. A non-empty `error` implies it. */
+    invalid?: boolean;
     /** Shows the current value at the end of the label row (tabular numbers). */
     showValue?: boolean;
     /** Formats the displayed value and `aria-valuetext` (e.g. `(v) => \`${v} °C\``). */
     formatValue?: (value: number) => string;
+    /** Tier. Default: the tier of the surrounding control (a form, a panel), else `m`. */
     size?: ControlSize;
-    className?: string;
+    /** Color of the filled part of the track. */
+    tone?: Tone;
+    /** Id of the range input; generated when omitted. */
+    id?: string;
+    /** Name of the range input when there is no `label`. */
     "aria-label"?: string;
+    "aria-describedby"?: string;
+    labels?: Partial<SliderLabels>;
 };
-declare function SliderRoot({ value: valueProp, defaultValue, min: minProp, max: maxProp, step: stepProp, disabled, onValueChange, label, showValue, formatValue, size, className, "aria-label": ariaLabel, }: SliderRootProps): import("react/jsx-runtime").JSX.Element;
-declare namespace SliderRoot {
-    var displayName: string;
-}
-export declare const Slider: {
-    Root: typeof SliderRoot;
-};
-export {};
-//# sourceMappingURL=Slider.d.ts.map
+/**
+ * A single value on a range, framed like every field: label row (with the value), the track
+ * with a glass thumb, then hint or error. `className`, `ref` and the rest go to the frame, `id`
+ * and `aria-label` to the range input.
+ */
+export declare function Slider({ value: valueProp, defaultValue, onValueChange, min, max, step, disabled, invalid, label, required, optional, hint, error, showValue, formatValue, size: sizeProp, tone, id, className, style, "aria-label": ariaLabel, "aria-describedby": ariaDescribedBy, labels: labelsProp, ...rest }: SliderProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/smart-filter/SmartFilter.d.ts

@@ -0,0 +1,105 @@
+import * as React from "react";
+import type { ControlSize } from "@/internal/states";
+import { type SmartFilterValue } from "./model";
+export type { SmartFilterMode, SmartFilterSelection, SmartFilterValue } from "./model";
+export { matchesSmartFilter, resolveSmartFilterValues } from "./model";
+export type SmartFilterOption = {
+    value: string;
+    label: string;
+    /** A decorative icon before the label (`<Icon name="…" />`). */
+    icon?: React.ReactNode;
+};
+export type SmartFilterField = {
+    /** Key of the field in the value. */
+    key: string;
+    label: string;
+    options: SmartFilterOption[];
+    /**
+     * A fixed set of values (default `true`): hiding every value at once is not allowed. Set `false`
+     * for an open set (services, users) that can change under the selection.
+     */
+    finite?: boolean;
+};
+/** System strings. `{query}`, `{value}`, `{field}`, `{fields}`, `{count}` are substituted. */
+export type SmartFilterLabels = {
+    /** Text of the filter button. */
+    filter: string;
+    /** Placeholder and accessible name of the search field. */
+    searchPlaceholder: string;
+    /** `aria-label` of the search clear button. */
+    clearSearch: string;
+    /** The first row of the panel while typing. */
+    searchText: string;
+    /** Fields with no matches while typing. */
+    noMatches: string;
+    /** Footer hint. */
+    hint: string;
+    /** Footer counter. */
+    count: string;
+    /** Footer reset button. */
+    reset: string;
+    /** Collapsed values of a field. */
+    more: string;
+    /** Chips row: the add button. */
+    add: string;
+    /** Chips row: clear all. */
+    clearAll: string;
+    /** Title of a value. */
+    showValue: string;
+    /** Name of the «−» action of a value. */
+    hideValue: string;
+    /** Name of the «−» action of a hidden value. */
+    unhideValue: string;
+    /** Prefix of a hidden value. */
+    not: string;
+    /** Text of a "show" tag. */
+    chipInclude: string;
+    /** Text of a "hide" tag. */
+    chipExclude: string;
+    /** `aria-label` of a tag's remove button. */
+    remove: string;
+};
+export type SmartFilterRootProps = {
+    /** The fields this screen filters by, in display order. Empty: only the search remains. */
+    fields: readonly SmartFilterField[];
+    /** Selection per field key. */
+    value?: SmartFilterValue;
+    defaultValue?: SmartFilterValue;
+    onValueChange?: (value: SmartFilterValue) => void;
+    /** Free-text search. Applied as typed; debounce it in the owner if needed. */
+    search?: string;
+    defaultSearch?: string;
+    onSearchChange?: (search: string) => void;
+    size?: ControlSize;
+    /** Values of one field shown before «Ещё N». Default 12. */
+    collapsedLimit?: number;
+    labels?: Partial<SmartFilterLabels>;
+    className?: string;
+    /** `SmartFilter.Toolbar` and `SmartFilter.Chips`. */
+    children: React.ReactNode;
+    ref?: React.Ref<HTMLDivElement>;
+};
+declare function SmartFilterRoot({ fields, value, defaultValue, onValueChange, search, defaultSearch, onSearchChange, size, collapsedLimit, labels, className, children, ref, }: SmartFilterRootProps): import("react/jsx-runtime").JSX.Element;
+declare namespace SmartFilterRoot {
+    var displayName: string;
+}
+export type SmartFilterToolbarProps = Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
+    ref?: React.Ref<HTMLDivElement>;
+};
+declare function SmartFilterToolbar({ className, ...rest }: SmartFilterToolbarProps): import("react/jsx-runtime").JSX.Element;
+declare namespace SmartFilterToolbar {
+    var displayName: string;
+}
+export type SmartFilterChipsProps = Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
+    ref?: React.Ref<HTMLDivElement>;
+};
+/** The applied filters as removable tags, with "add" and "clear all". Renders nothing without filters. */
+declare function SmartFilterChips({ className, ...rest }: SmartFilterChipsProps): import("react/jsx-runtime").JSX.Element | null;
+declare namespace SmartFilterChips {
+    var displayName: string;
+}
+export declare const SmartFilter: {
+    Root: typeof SmartFilterRoot;
+    Toolbar: typeof SmartFilterToolbar;
+    Chips: typeof SmartFilterChips;
+};

package/dist/components/smart-filter/model.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The filter model: every field has two lists, what to show and what to hide. Pure functions with
+ * no state; the owner keeps the value (`SmartFilter.Root value / onValueChange`).
+ */
+export type SmartFilterSelection = {
+    /** Values to show. Empty means "any". */
+    include: string[];
+    /** Values to hide. */
+    exclude: string[];
+};
+/** Selection per field key. Fields without a selection are absent. */
+export type SmartFilterValue = Record<string, SmartFilterSelection>;
+export type SmartFilterMode = "include" | "exclude";
+export declare function selectionModeOf(selection: SmartFilterSelection | undefined, value: string): SmartFilterMode | null;
+/** Sets the mode of a value; asking for the mode it already has clears it. A value is never in both lists. */
+export declare function toggleSelectionMode(selection: SmartFilterSelection | undefined, value: string, mode: SmartFilterMode): SmartFilterSelection;
+/** Drops a value from both lists. */
+export declare function removeSelectionValue(selection: SmartFilterSelection | undefined, value: string): SmartFilterSelection;
+export declare function selectionSize(selection: SmartFilterSelection | undefined): number;
+/** Sets one field's selection; an empty selection removes the field from the value. */
+export declare function withSelection(value: SmartFilterValue, key: string, selection: SmartFilterSelection): SmartFilterValue;
+/**
+ * For a field with a fixed set of values: whether `value` can be hidden without hiding everything.
+ * "Everything hidden" is an empty result, so it is not allowed.
+ */
+export declare function canExcludeValue(selection: SmartFilterSelection | undefined, value: string, all: readonly string[]): boolean;
+/** Whether a value passes a selection: `include` empty means any, `exclude` rejects. */
+export declare function matchesSmartFilter(selection: SmartFilterSelection | undefined, value: string): boolean;
+/**
+ * Turns a selection over a fixed set of values into the list to ask a server for: "hide" becomes
+ * "all except". An empty array means no filter (also when the selection covers every value).
+ */
+export declare function resolveSmartFilterValues(selection: SmartFilterSelection | undefined, all: readonly string[]): string[];

package/dist/components/spinner/Spinner.d.ts

@@ -0,0 +1,22 @@
+import * as React from "react";
+import type { ControlSize, TextTone } from "@/internal/states";
+export type SpinnerLabels = {
+    /** Text read by screen readers while the spinner is shown. */
+    loading: string;
+};
+export type SpinnerProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> & {
+    /**
+     * Explicit size on the icon scale (xs 14 · s 16 · m 20 · l 24 · xl 32). Without it the spinner
+     * follows its host like an `Icon`: the host's icon size, else the nearest control tier, else 16.
+     */
+    size?: ControlSize;
+    /** Ring color; `default` inherits `currentColor`. */
+    tone?: TextTone;
+    labels?: Partial<SpinnerLabels>;
+    ref?: React.Ref<HTMLSpanElement>;
+};
+/**
+ * Indeterminate loading indicator: a rotating ring with a gap. A `role="status"` region with
+ * `labels.loading` for screen readers; pass `aria-hidden` when the host already says it is busy.
+ */
+export declare function Spinner({ size: sizeProp, tone, labels: labelsProp, className, ...rest }: SpinnerProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/stepper/Stepper.d.ts

@@ -1,79 +1,70 @@
 import * as React from "react";
 import type { ControlSize } from "@/internal/states";
-/** Step state: derived from the Root `value` (before → `completed`, equal → `active`, after → `pending`) unless set on the step. */
-export type StepperStepStatus = "pending" | "active" | "completed" | "error";
-export type StepperRootProps = {
+/** Item state: derived from the Root `value` (before → `completed`, equal → `active`, after → `pending`) unless set on the item. */
+export type StepperItemStatus = "pending" | "active" | "completed" | "danger";
+export type StepperRootProps = Omit<React.OlHTMLAttributes<HTMLOListElement>, "defaultValue" | "onChange"> & {
     /** Default `vertical`. A horizontal stepper stacks vertically in containers narrower than 480px. */
     orientation?: "horizontal" | "vertical";
     /** Current step (0-based), controlled. */
     value?: number;
     /** Initial step when uncontrolled. Default `0`. */
     defaultValue?: number;
-    /** Called with the step index when a step is clicked. */
+    /** Called with the item index when an item is clicked. */
     onValueChange?: (index: number) => void;
     size?: ControlSize;
-    /** `Stepper.Step` elements as direct children (an array from `map` is fine). */
-    children: React.ReactNode;
-    className?: string;
-} & Omit<React.OlHTMLAttributes<HTMLOListElement>, "children" | "defaultValue" | "onChange">;
+    ref?: React.Ref<HTMLOListElement>;
+};
 declare function StepperRoot({ orientation, value: valueProp, defaultValue, onValueChange, size, children, className, ...rest }: StepperRootProps): import("react/jsx-runtime").JSX.Element;
 declare namespace StepperRoot {
     var displayName: string;
 }
-export type StepperStepProps = {
-    /** Overrides the status derived from the Root `value` (e.g. `error`). */
-    status?: StepperStepStatus;
-    children: React.ReactNode;
-} & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" | "children">;
-export type StepperIndicatorProps = {
-    /** Replaces the default content (step number, or a check when completed). */
+export type StepperItemProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type"> & {
+    /** Overrides the status derived from the Root `value` (e.g. `danger`). */
+    status?: StepperItemStatus;
+    ref?: React.Ref<HTMLButtonElement>;
+};
+declare function StepperItem({ status: statusProp, children, className, disabled, onClick, ...rest }: StepperItemProps): import("react/jsx-runtime").JSX.Element;
+declare namespace StepperItem {
+    var displayName: string;
+}
+type SpanProps = React.HTMLAttributes<HTMLSpanElement> & {
+    ref?: React.Ref<HTMLSpanElement>;
+};
+export type StepperIndicatorProps = SpanProps & {
+    /** Replaces the default content (the item number, or a check when completed). */
     children?: React.ReactNode;
-    className?: string;
 };
-declare function StepperIndicator({ children, className }: StepperIndicatorProps): import("react/jsx-runtime").JSX.Element;
+declare function StepperIndicator({ children, className, ...rest }: StepperIndicatorProps): import("react/jsx-runtime").JSX.Element;
 declare namespace StepperIndicator {
     var displayName: string;
 }
-export type StepperContentProps = {
-    children: React.ReactNode;
-    className?: string;
-};
+export type StepperContentProps = SpanProps;
 /** Text column: `Stepper.Title` and optional `Stepper.Description`. */
-declare function StepperContent({ children, className }: StepperContentProps): import("react/jsx-runtime").JSX.Element;
+declare function StepperContent({ className, ...rest }: StepperContentProps): import("react/jsx-runtime").JSX.Element;
 declare namespace StepperContent {
     var displayName: string;
 }
-export type StepperTitleProps = {
-    children: React.ReactNode;
-    className?: string;
-};
-declare function StepperTitle({ children, className }: StepperTitleProps): import("react/jsx-runtime").JSX.Element;
+export type StepperTitleProps = SpanProps;
+declare function StepperTitle({ className, ...rest }: StepperTitleProps): import("react/jsx-runtime").JSX.Element;
 declare namespace StepperTitle {
     var displayName: string;
 }
-export type StepperDescriptionProps = {
-    children: React.ReactNode;
-    className?: string;
-};
-declare function StepperDescription({ children, className }: StepperDescriptionProps): import("react/jsx-runtime").JSX.Element;
+export type StepperDescriptionProps = SpanProps;
+declare function StepperDescription({ className, ...rest }: StepperDescriptionProps): import("react/jsx-runtime").JSX.Element;
 declare namespace StepperDescription {
     var displayName: string;
 }
-export type StepperArrowProps = {
-    className?: string;
+export type StepperArrowProps = Omit<React.SVGAttributes<SVGSVGElement>, "children"> & {
+    ref?: React.Ref<SVGSVGElement>;
 };
-/** Trailing chevron for vertical steps that open a page or panel. */
-declare function StepperArrow({ className }: StepperArrowProps): import("react/jsx-runtime").JSX.Element;
+/** Trailing chevron for vertical items that open a page or panel. */
+declare function StepperArrow({ className, ...rest }: StepperArrowProps): import("react/jsx-runtime").JSX.Element;
 declare namespace StepperArrow {
     var displayName: string;
 }
 export declare const Stepper: {
     Root: typeof StepperRoot;
-    Step: React.ForwardRefExoticComponent<{
-        /** Overrides the status derived from the Root `value` (e.g. `error`). */
-        status?: StepperStepStatus;
-        children: React.ReactNode;
-    } & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children" | "type"> & React.RefAttributes<HTMLButtonElement>>;
+    Item: typeof StepperItem;
     Indicator: typeof StepperIndicator;
     Content: typeof StepperContent;
     Title: typeof StepperTitle;
@@ -81,4 +72,3 @@ export declare const Stepper: {
     Arrow: typeof StepperArrow;
 };
 export {};
-//# sourceMappingURL=Stepper.d.ts.map

package/dist/components/switch/Switch.d.ts

@@ -1,52 +1,34 @@
-import * as React from "react";
+import type * as React from "react";
+import { type ChoiceLabelProps } from "@/internal/ChoiceField";
 import type { ControlSize } from "@/internal/states";
-type InputPassthrough = Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "size" | "checked" | "defaultChecked" | "onChange" | "children">;
-export type SwitchRootProps = InputPassthrough & {
+export type SwitchRootProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "size" | "checked" | "defaultChecked" | "onChange"> & {
     checked?: boolean;
     defaultChecked?: boolean;
     onCheckedChange?: (checked: boolean) => void;
-    /** Invalid state; also set while a `Switch.Error` is mounted. */
+    /** Invalid state; a non-empty `error` implies it. */
     invalid?: boolean;
+    /** Help text under the label text. Hidden while `error` is shown. */
+    hint?: React.ReactNode;
+    /** Error message in the hint slot; implies `invalid`. */
+    error?: React.ReactNode;
+    /** Tier. Default: the tier of the surrounding control (a form, a panel), else `m`. */
     size?: ControlSize;
-    /** Stretch to the container width. By default the field is as wide as its content. */
-    fullWidth?: boolean;
+    /** `Switch.Label`; without it only the track renders (give it an `aria-label`). */
     children?: React.ReactNode;
+    /** The native `role="switch"` input. */
+    ref?: React.Ref<HTMLInputElement>;
 };
-export type SwitchLabelProps = {
-    children?: React.ReactNode;
-    className?: string;
-} & Omit<React.HTMLAttributes<HTMLLabelElement>, "htmlFor" | "size">;
-export type SwitchHintProps = {
-    children: React.ReactNode;
-    className?: string;
-} & Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">;
-declare function SwitchHint({ children, className, ...rest }: SwitchHintProps): import("react/jsx-runtime").JSX.Element;
-declare namespace SwitchHint {
+declare function SwitchRoot({ id, checked: checkedProp, defaultChecked, onCheckedChange, invalid, hint, error, size: sizeProp, disabled, readOnly, className, "aria-describedby": ariaDescribedBy, children, ref, ...inputRest }: SwitchRootProps): import("react/jsx-runtime").JSX.Element;
+declare namespace SwitchRoot {
     var displayName: string;
 }
-export type SwitchErrorProps = SwitchHintProps;
-declare function SwitchError({ children, className, ...rest }: SwitchErrorProps): import("react/jsx-runtime").JSX.Element;
-declare namespace SwitchError {
+export type SwitchLabelProps = ChoiceLabelProps;
+declare function SwitchLabel(props: SwitchLabelProps): import("react/jsx-runtime").JSX.Element;
+declare namespace SwitchLabel {
     var displayName: string;
 }
 export declare const Switch: {
-    Root: React.ForwardRefExoticComponent<InputPassthrough & {
-        checked?: boolean;
-        defaultChecked?: boolean;
-        onCheckedChange?: (checked: boolean) => void;
-        /** Invalid state; also set while a `Switch.Error` is mounted. */
-        invalid?: boolean;
-        size?: ControlSize;
-        /** Stretch to the container width. By default the field is as wide as its content. */
-        fullWidth?: boolean;
-        children?: React.ReactNode;
-    } & React.RefAttributes<HTMLInputElement>>;
-    Label: React.ForwardRefExoticComponent<{
-        children?: React.ReactNode;
-        className?: string;
-    } & Omit<React.HTMLAttributes<HTMLLabelElement>, "size" | "htmlFor"> & React.RefAttributes<HTMLLabelElement>>;
-    Hint: typeof SwitchHint;
-    Error: typeof SwitchError;
+    Root: typeof SwitchRoot;
+    Label: typeof SwitchLabel;
 };
 export {};
-//# sourceMappingURL=Switch.d.ts.map