themelia-react-ui 2.0.3 → 2.0.5

package/dist/components/base/choice-inputs/switch-card.d.ts

@@ -10,6 +10,13 @@
 import { type LucideIcon } from 'lucide-react';
 import * as React from 'react';
 export interface SwitchCardProps {
+    /** Editable control ref; the forwarded ref continues to name the outer row/card. */
+    controlRef?: React.Ref<HTMLElement>;
+    /** Blur callback from the editable control. */
+    onBlur?: React.FocusEventHandler<HTMLElement>;
+    /** Id of the editable control, including external FormField associations. */
+    id?: string;
+    'aria-invalid'?: React.AriaAttributes['aria-invalid'];
     /** Additional supporting/error descriptions associated with the editable control. */
     'aria-describedby'?: string;
     /** Card title, also the switch's accessible name. */

package/dist/components/base/choice-inputs/toggle-field.d.ts

@@ -15,6 +15,13 @@
 import type { ReactNode } from 'react';
 export type ToggleFieldKind = 'switch' | 'checkbox';
 export interface ToggleFieldProps {
+    /** Editable control ref; the forwarded ref continues to name the outer row/card. */
+    controlRef?: React.Ref<HTMLElement>;
+    /** Blur callback from the editable control. */
+    onBlur?: React.FocusEventHandler<HTMLElement>;
+    /** Id of the editable control, including external FormField associations. */
+    id?: string;
+    'aria-invalid'?: React.AriaAttributes['aria-invalid'];
     /** Additional supporting/error descriptions associated with the editable control. */
     'aria-describedby'?: string;
     /** Control label. */

package/dist/components/base/combobox/index.d.ts

@@ -10,9 +10,9 @@
  * The compound root is exported as `ComboboxRoot` so the canonical `Combobox`
  * name stays with the opinionated feature component.
  */
-export { Combobox as ComboboxRoot, ComboboxValue, ComboboxPortal, ComboboxPositioner, ComboboxList, ComboboxItemIndicator, ComboboxEmpty, ComboboxStatus, ComboboxGroup, ComboboxGroupLabel, ComboboxCollection, ComboboxChips, ComboboxChipsInput, ComboboxBackdrop, ComboboxArrow, useComboboxFilter, } from '../../ui/combobox';
+export { Combobox as ComboboxRoot, ComboboxValue, ComboboxPortal, ComboboxPositioner, ComboboxItemIndicator, ComboboxEmpty, ComboboxStatus, ComboboxGroup, ComboboxGroupLabel, ComboboxCollection, ComboboxChips, ComboboxChipsInput, ComboboxBackdrop, ComboboxArrow, useComboboxFilter, } from '../../ui/combobox';
 import { type ComponentProps } from 'react';
-import { ComboboxItem as Item, ComboboxPopup as Popup, ComboboxInput as Input, ComboboxInputTrigger as InputTrigger, ComboboxClear as Clear, ComboboxChip as Chip, ComboboxTrigger as Trigger, ComboboxSeparator as Separator } from '../../ui/combobox';
+import { ComboboxList as List, ComboboxItem as Item, ComboboxPopup as Popup, ComboboxInput as Input, ComboboxInputTrigger as InputTrigger, ComboboxClear as Clear, ComboboxChip as Chip, ComboboxTrigger as Trigger, ComboboxSeparator as Separator } from '../../ui/combobox';
 import { type CollectionDensity } from '../popover/popover.recipes';
 import { type StringsProp } from '../../../lib/strings';
 import { type ComboboxControlStrings } from './combobox.strings';
@@ -41,6 +41,8 @@ export declare function ComboboxChip({ strings: stringsProp, ...props }: Combobo
     removeLabel?: string;
 }>;
 export declare function ComboboxPopup({ className, ...props }: ComponentProps<typeof Popup>): import("react").FunctionComponentElement<import("@base-ui/react").AutocompletePopupProps>;
+/** The list owns one compact collection inset inside the flush popup. */
+export declare function ComboboxList({ className, ...props }: ComponentProps<typeof List>): import("react").FunctionComponentElement<import("@base-ui/react").AutocompleteListProps>;
 export declare function ComboboxInput({ className, ...props }: ComponentProps<typeof Input>): import("react").FunctionComponentElement<import("@base-ui/react").AutocompleteInputProps>;
 export declare function ComboboxTrigger({ className, ...props }: ComponentProps<typeof Trigger>): import("react").FunctionComponentElement<import("@base-ui/react").ComboboxTriggerProps>;
 export declare function ComboboxItem({ className, size, density, children, ...props }: ComponentProps<typeof Item> & {

package/dist/components/base/date-pickers/datepicker.types.d.ts

@@ -1,3 +1,4 @@
+import type { AriaAttributes, FocusEventHandler, Ref } from 'react';
 import type { LucideIcon } from 'lucide-react';
 import type { DateRange, PropsSingle, PropsRange, PropsMulti, Locale } from 'react-day-picker';
 import type { FormControlSize } from '../../../lib/ui-provider';
@@ -65,6 +66,12 @@ export interface DatePickerStrings {
     year: string;
 }
 export interface DatePickerBaseProps {
+    /** Trigger ref for focus and form adapters; the forwarded ref remains the field root. */
+    triggerRef?: Ref<HTMLButtonElement>;
+    /** Native trigger blur callback. */
+    onBlur?: FocusEventHandler<HTMLButtonElement>;
+    'aria-describedby'?: string;
+    'aria-invalid'?: AriaAttributes['aria-invalid'];
     /** Trigger field size. Explicit values override the provider density scale; fallback is md. */
     size?: FormControlSize;
     /** Caption above the trigger, associated through `htmlFor`. Omit when an external FormField owns the chrome. */

package/dist/components/base/feedback/alert.d.ts

@@ -1,5 +1,5 @@
 /**
- * Alert — base notice primitive with semantic variants and responsive actions.
+ * Alert — base notice primitive with semantic variants and container-driven actions.
  *
  * Package-owned notice inspired by ReUI's alert layout. Consumers import this
  * base alert for the library's typography, token, and DOM-hook contract.

package/dist/components/base/forms/controlled-form-field.d.ts

@@ -1,14 +1,14 @@
 /**
- * ControlledFormField — react-hook-form integration for the optional-peer-free
- * `FormField` presentation component. Keeping this binding in its own module
- * prevents unrelated display and form-chrome consumers from loading RHF.
+ * ControlledFormField — react-hook-form integration for the presentational
+ * `FormField` component. Runtime state bindings stay in this module; the
+ * published family still reports RHF for its exported bindings and types.
  */
 import type { ComponentProps, ReactNode } from 'react';
 import { type Control, type ControllerFieldState, type ControllerRenderProps, type FieldPath, type FieldValues, type RegisterOptions } from 'react-hook-form';
 import { FormField } from './form-field';
 import { type ControlledFormFieldStrings } from './controlled-form-field.strings';
 import { type StringsProp } from '../../../lib/strings';
-type FieldChromeProps = Omit<ComponentProps<typeof FormField>, 'children' | 'error' | 'htmlFor'>;
+type FieldChromeProps = Omit<ComponentProps<typeof FormField>, 'children' | 'error'>;
 export type FormFieldErrorGetter<TName extends string> = (field: TName) => string | undefined;
 export interface ControlledFormFieldProps<TFieldValues extends FieldValues, TName extends FieldPath<TFieldValues>> extends FieldChromeProps {
     /** Field name in the react-hook-form schema. */
@@ -18,14 +18,14 @@ export interface ControlledFormFieldProps<TFieldValues extends FieldValues, TNam
     /** Validation rules passed to react-hook-form. */
     rules?: RegisterOptions<TFieldValues, TName>;
     /** Validation message, overriding the one derived from form state. */
-    error?: FormFieldErrorGetter<TName>;
+    error?: ReactNode | FormFieldErrorGetter<TName>;
     /** Overrides the field's own copy. */
     strings?: StringsProp<ControlledFormFieldStrings>;
     children: (field: ControllerRenderProps<TFieldValues, TName>, 
     /** Validation message, overriding the one derived from form state. */
     error: string | undefined, invalid: boolean, fieldState: ControllerFieldState) => ReactNode;
 }
-export declare function ControlledFormField<TFieldValues extends FieldValues, TName extends FieldPath<TFieldValues>>({ name, control, rules, error: errorGetter, strings: stringsProp, children, ...chromeProps }: ControlledFormFieldProps<TFieldValues, TName>): import("react").JSX.Element;
+export declare function ControlledFormField<TFieldValues extends FieldValues, TName extends FieldPath<TFieldValues>>({ name, control, rules, error: errorProp, strings: stringsProp, children, ...chromeProps }: ControlledFormFieldProps<TFieldValues, TName>): import("react").JSX.Element;
 export declare namespace ControlledFormField {
     var displayName: string;
 }

package/dist/components/base/forms/form-field.d.ts

@@ -1,7 +1,9 @@
 /**
- * FormField — optional-peer-free presentation chrome for a label, control,
- * hint/helper, and validation error. The react-hook-form integration lives in
- * `controlled-form-field.tsx` so presentational consumers do not load RHF.
+ * FormField — presentation chrome for a label, control, hint/helper and error.
+ * This implementation keeps presentation separate from RHF state bindings.
+ * The published `base/forms` family exports those bindings and types, so use
+ * its listed react-hook-form peer even when selecting only FormField. Installing
+ * that peer does not require adopting RHF for the app's own form state.
  */
 import * as React from 'react';
 import { type ComponentPropsWithoutRef, type ReactNode } from 'react';

package/dist/components/base/forms/form-sizing.d.ts

@@ -68,7 +68,7 @@ export declare const formControlMinHeightClasses: {
 /**
  * The one field frame, drawn by `Input` on its native field and by
  * `formFieldTriggerClasses` on button-shaped triggers: the `--input` boundary,
- * inner radius, transparent fill (the library is intentionally flat), control
+ * default radius, transparent fill (the library is intentionally flat), control
  * height, editable text size, control padding and the shared focus, invalid and
  * disabled states. Layout (`flex`, width) stays with each owner.
  *
@@ -97,9 +97,9 @@ export declare const formTextareaSizeClasses: {
  * line height, so the inset follows the editable text size on every pointer.
  */
 export declare const formTextareaInsetClasses: {
-    readonly sm: "py-[calc((var(--height-control)*8/9*var(--density-scale)-1lh)/2-1px)]";
+    readonly sm: "py-[calc((var(--height-control)*7/8*var(--density-scale)-1lh)/2-1px)]";
     readonly md: "py-[calc((var(--height-control)*var(--density-scale)-1lh)/2-1px)]";
-    readonly lg: "py-[calc((var(--height-control)*10/9*var(--density-scale)-1lh)/2-1px)]";
+    readonly lg: "py-[calc((var(--height-control)*9/8*var(--density-scale)-1lh)/2-1px)]";
 };
 /**
  * Top offsets that centre multi-line field affordances on the first line, where a
@@ -108,14 +108,14 @@ export declare const formTextareaInsetClasses: {
  */
 export declare const formTextareaAffordanceTopClasses: {
     readonly target: {
-        readonly sm: "top-[calc((var(--height-control)*8/9-1.375rem)*var(--density-scale)/2)]";
+        readonly sm: "top-[calc((var(--height-control)*7/8-1.375rem)*var(--density-scale)/2)]";
         readonly md: "top-[calc((var(--height-control)-1.375rem)*var(--density-scale)/2)]";
-        readonly lg: "top-[calc((var(--height-control)*10/9-1.375rem)*var(--density-scale)/2)]";
+        readonly lg: "top-[calc((var(--height-control)*9/8-1.375rem)*var(--density-scale)/2)]";
     };
     readonly icon: {
-        readonly sm: "top-[calc((var(--height-control)*8/9*var(--density-scale)-var(--icon))/2)]";
+        readonly sm: "top-[calc((var(--height-control)*7/8*var(--density-scale)-var(--icon))/2)]";
         readonly md: "top-[calc((var(--height-control)*var(--density-scale)-var(--icon))/2)]";
-        readonly lg: "top-[calc((var(--height-control)*10/9*var(--density-scale)-var(--icon))/2)]";
+        readonly lg: "top-[calc((var(--height-control)*9/8*var(--density-scale)-var(--icon))/2)]";
     };
 };
 export declare const formLabelSizeClasses: {

package/dist/components/base/forms/index.d.ts

@@ -1,4 +1,5 @@
 export * from './form-field';
 export * from './controlled-form-field';
+export * from './server-errors';
 export * from './workflow';
 export { OperationPasswordForm, type OperationPasswordFormProps } from './operation-password-form';

package/dist/components/base/forms/server-errors.d.ts

@@ -0,0 +1,16 @@
+import type { FieldPath, FieldValues, UseFormSetError } from 'react-hook-form';
+/** Flat server validation messages; transport libraries keep ownership of requests. */
+export type ServerErrors<TName extends string = string> = Partial<Record<TName, string | readonly string[]>>;
+export interface ApplyServerErrorsOptions<TFieldValues extends FieldValues> {
+    /** Allowed schema paths. Unknown server keys are reported at the root. */
+    fields: readonly FieldPath<TFieldValues>[];
+    /** Root error path for unknown fields and general errors. Defaults to root.server. */
+    root?: `root.${string}`;
+}
+/**
+ * Apply an untrusted transport error bag without importing a transport or RHF at
+ * runtime. The allowlist prevents unknown server keys from becoming form fields.
+ * Invalid/empty messages are ignored; arrays retain every string message.
+ * Returns the number of field/root errors applied.
+ */
+export declare function applyServerErrors<TFieldValues extends FieldValues>(setError: UseFormSetError<TFieldValues>, errors: unknown, { fields, root }: ApplyServerErrorsOptions<TFieldValues>): number;

package/dist/components/base/forms/workflow.d.ts

@@ -1,6 +1,7 @@
 /** Form workflow primitives — section chrome, errors, dirty state, and submit state. */
 import type { ReactNode } from 'react';
 import type { ButtonProps } from '../buttons';
+import { type CardProps } from '../cards';
 import type { SmartCardSurface } from '../cards';
 import type { AlertTone } from '../feedback';
 export interface FormSectionProps {
@@ -13,13 +14,21 @@ export interface FormSectionProps {
     children?: ReactNode;
     /** Content below the section body. */
     footer?: ReactNode;
-    /** Outer chrome. Use `flat` when the section already sits inside a card. */
+    /** Outer chrome. Use `flat` with `padding="none"` inside a padded Card. */
     surface?: SmartCardSurface;
+    /** Card region insets. Defaults to Card's ordinary inset; use `none` when the parent already owns padding. */
+    padding?: CardProps['padding'];
+    /**
+     * Section title size. Embedded `surface="flat" padding="none"` inside a padded
+     * Card defaults to the subordinate `sm` title, below the card's own title;
+     * otherwise Card's default applies.
+     */
+    titleSize?: CardProps['titleSize'];
     className?: string;
     /** Merged onto the section body. */
     contentClassName?: string;
 }
-export declare function FormSection({ title, description, actions, children, footer, surface, className, contentClassName, }: FormSectionProps): import("react").JSX.Element;
+export declare function FormSection({ title, description, actions, children, footer, surface, padding, titleSize, className, contentClassName, }: FormSectionProps): import("react").JSX.Element;
 export interface FormActionsBarProps {
     /** Action content used when `trailing` is not provided. */
     children?: ReactNode;

package/dist/components/base/forms-numeric/coordinates-input.d.ts

@@ -17,6 +17,10 @@ export interface CoordinatesInputStrings {
     lngPlaceholder: string;
     /** Anchor text for the Google Maps preview link. Empty string hides it. */
     previewLinkLabel: string;
+    /** Accessible name for the latitude input while `latLabel` is empty. */
+    latAccessibleLabel: string;
+    /** Accessible name for the longitude input while `lngLabel` is empty. */
+    lngAccessibleLabel: string;
 }
 export declare const defaultCoordinatesInputStrings: CoordinatesInputStrings;
 export interface CoordinatesInputProps {

package/dist/components/base/metadata-list/metadata-list.d.ts

@@ -33,6 +33,8 @@ export type MetadataDensity = 'default' | 'compact';
 type MetadataListSharedProps = {
     /** How many columns the grid layout uses. Accepts a per-breakpoint value. */
     columns?: ResponsiveValue<1 | 2 | 3 | 4>;
+    /** Measure responsive grid columns against this list's own width (default) or the viewport. */
+    adaptTo?: 'viewport' | 'container';
     /** Row spacing. `compact` tightens the list for dense panels. */
     density?: MetadataDensity;
     /** Copy shown for an item whose value is empty. Defaults to an em dash. */
@@ -75,7 +77,7 @@ type MetadataInlineProps = MetadataListSharedProps & {
     valueAlign?: never;
 };
 export type MetadataListProps = MetadataGridRowsProps | MetadataInlineProps;
-export declare function MetadataList({ items, columns, density, emptyLabel, title, titleSeparator, className, layout, separator, itemSeparator, valueAlign, strings: stringsProp, }: MetadataListProps): React.JSX.Element | null;
+export declare function MetadataList({ items, columns, adaptTo, density, emptyLabel, title, titleSeparator, className, layout, separator, itemSeparator, valueAlign, strings: stringsProp, }: MetadataListProps): React.JSX.Element | null;
 export declare namespace MetadataList {
     var displayName: string;
 }

package/dist/components/base/navigation/dropdown-menu.d.ts

@@ -2,7 +2,7 @@ import * as React from 'react';
 import { Menu as MenuPrimitive } from '@base-ui/react/menu';
 import { type CollectionDensity } from '../popover/popover.recipes';
 declare function DropdownMenu({ ...props }: MenuPrimitive.Root.Props): React.JSX.Element;
-declare function DropdownMenuPortal({ container, ...props }: MenuPrimitive.Portal.Props): React.JSX.Element;
+declare function DropdownMenuPortal({ container, className, ...props }: MenuPrimitive.Portal.Props): React.JSX.Element;
 declare function DropdownMenuTrigger({ children, ...props }: MenuPrimitive.Trigger.Props): React.JSX.Element;
 declare function DropdownMenuContent({ positionMethod, align, alignOffset, side, sideOffset, className, density: densityProp, ...props }: MenuPrimitive.Popup.Props & Pick<MenuPrimitive.Positioner.Props, 'align' | 'alignOffset' | 'side' | 'sideOffset' | 'positionMethod'> & {
     /** Vertical row rhythm. Inherits in submenus; defaults to default. */

package/dist/components/base/navigation/page-header/page-header-commands.d.ts

@@ -3,12 +3,12 @@
  *
  * The role chooses each command's treatment and place: outline secondary
  * commands, then one solid primary command, then the More actions menu for
- * overflow and destructive commands, which always closes the row. Below `sm`,
- * secondary commands collapse into that menu through CSS alone, so server and
- * client markup agree. PageHeading owns the row, so every header that takes
- * `primaryAction` and `secondaryActions` places its commands the same way.
+ * overflow and destructive commands, which always closes the row. Below the
+ * named header container breakpoint, every command collapses into that menu
+ * through CSS alone, so server and client markup agree. Both page and section
+ * headers use this owner for the same command behavior.
  */
-import type { ComponentType, MouseEvent, ReactNode } from 'react';
+import { type ComponentType, type MouseEvent, type ReactNode } from 'react';
 /**
  * A page command described by its role. `primaryAction` and `secondaryActions`
  * choose the treatment, so a command carries no tone or button style.
@@ -59,15 +59,22 @@ export interface PageHeaderLinkRenderProps {
 export type PageHeaderLinkRenderer = (props: PageHeaderLinkRenderProps) => ReactNode;
 /** Native anchor fallback, matching the layout default: external links open a new tab. */
 export declare const defaultPageHeaderLinkRenderer: PageHeaderLinkRenderer;
-/** Secondary commands rendered as buttons from `sm` up; later ones overflow. */
+/** Secondary commands rendered as buttons on wide headers; later ones overflow. */
 export declare const PAGE_HEADER_INLINE_SECONDARY_LIMIT = 2;
 export interface PageHeaderCommandsProps {
     primaryAction?: PageHeaderAction;
     secondaryActions?: readonly PageHeaderAction[];
+    /**
+     * How many routine secondary commands render as outline buttons on wide
+     * headers; later ones join the More actions menu. Use `1` or `0` when long
+     * labels beside the primary command would crowd the header; `Infinity`
+     * keeps every routine command inline. @default 2
+     */
+    maxVisibleSecondaryActions?: number;
     /** Accessible name of the More actions menu trigger. */
     moreActionsLabel: string;
     renderLink?: PageHeaderLinkRenderer;
 }
 /** Whether the header has any role-based command to render. */
 export declare function hasPageHeaderCommands(primaryAction: PageHeaderAction | undefined, secondaryActions: readonly PageHeaderAction[] | undefined): boolean;
-export declare function PageHeaderCommands({ primaryAction, secondaryActions, moreActionsLabel, renderLink, }: PageHeaderCommandsProps): import("react").JSX.Element | null;
+export declare function PageHeaderCommands({ primaryAction, secondaryActions, maxVisibleSecondaryActions, moreActionsLabel, renderLink, }: PageHeaderCommandsProps): import("react").JSX.Element | null;

package/dist/components/base/navigation/page-header/page-header.d.ts

@@ -7,7 +7,7 @@
  * on it.
  */
 import type { Key, ReactNode } from 'react';
-import { type HeadingTag } from '../../../typography';
+import { type HeadingSize, type HeadingTag } from '../../../typography';
 import { type BadgeTone } from '../../badge';
 import { type TextGap } from '../../structure';
 import { type PageHeaderAction, type PageHeaderLinkRenderer } from './page-header-commands';
@@ -41,6 +41,8 @@ export interface PageHeadingProps {
     textGap?: TextGap;
     /** Heading level for a plain-text `title`. Default: `'h2'`. Set for correct document outline. */
     headingTag?: HeadingTag;
+    /** Visual title scale, independent of heading level. Defaults to the subject role (`base`). */
+    titleSize?: HeadingSize;
     /** Convenience for a single badge beside the title. Ignored when `badges` is set. */
     badge?: PageHeadingBadge;
     /** Badges beside the title, in order. Takes precedence over `badge`. */
@@ -69,16 +71,23 @@ export interface PageHeadingProps {
     actions?: ReactNode;
     /**
      * The header's one main command: a solid primary button after the secondary
-     * commands, visible at every width.
+     * commands, placed in the command menu below 40rem of header width.
      */
     primaryAction?: PageHeaderAction;
     /**
      * Supporting commands in priority order. The first two render as outline
      * buttons before the primary command; the rest, and every destructive
      * command, move into the More actions menu, which always closes the row.
-     * Below `sm`, all secondary commands collapse into that menu.
+     * Below 40rem of header width, every command collapses into that menu.
      */
     secondaryActions?: readonly PageHeaderAction[];
+    /**
+     * How many routine secondary commands render as outline buttons on wide
+     * headers; later ones join the More actions menu. Use `1` or `0` when long
+     * labels beside the primary command would crowd the header; `Infinity`
+     * keeps every routine command inline. @default 2
+     */
+    maxVisibleSecondaryActions?: number;
     /** Accessible name of the More actions menu trigger. Default: `'More actions'`. */
     moreActionsLabel?: string;
     /** Renders `href` commands as framework links. Defaults to a native anchor. */
@@ -108,7 +117,7 @@ export interface PageHeadingProps {
      */
     withSeparator?: boolean;
 }
-export declare function PageHeading({ eyebrow, title, description, textGap, headingTag, badge, badges, breadcrumbs, leading, beforeTitle, titlePrefix, titleSuffix, afterDescription, actions, primaryAction, secondaryActions, moreActionsLabel, renderLink, children, className, contentClassName, eyebrowClassName, titleClassName, titleRowClassName, descriptionClassName, actionsClassName, withSeparator, }: PageHeadingProps): import("react").JSX.Element;
+export declare function PageHeading({ eyebrow, title, description, textGap, headingTag, titleSize, badge, badges, breadcrumbs, leading, beforeTitle, titlePrefix, titleSuffix, afterDescription, actions, primaryAction, secondaryActions, maxVisibleSecondaryActions, moreActionsLabel, renderLink, children, className, contentClassName, eyebrowClassName, titleClassName, titleRowClassName, descriptionClassName, actionsClassName, withSeparator, }: PageHeadingProps): import("react").JSX.Element;
 export declare namespace PageHeading {
     var displayName: string;
 }

package/dist/components/base/popover/popover.d.ts

@@ -26,8 +26,8 @@ export type PopoverContentInset = 'default' | 'compact' | 'flush';
 export type PopoverContentProps = PopoverContentBaseProps & {
     /**
      * Surface inset role. `default` is for card-like or multi-content popovers,
-     * `compact` for pure item/option collections, and `flush` when child regions
-     * own their padding.
+     * `compact` for item collections (or the small surface tier with explicit
+     * type="display"), and `flush` when child regions own their padding.
      */
     inset?: PopoverContentInset;
     /** Anatomy role; supplies the inferred inset only when inset is omitted. */
@@ -47,7 +47,7 @@ declare function PopoverTitle({ children, className, ...props }: PopoverTitleBas
 type PopoverDescriptionBaseProps = React.ComponentProps<typeof PopoverDescriptionPrimitive>;
 declare function PopoverDescription({ children, className, ...props }: PopoverDescriptionBaseProps): React.JSX.Element;
 type PopoverFooterProps = React.ComponentProps<'div'> & {
-    /** Leading supporting content, aligned with collection labels; children are trailing actions. */
+    /** Leading supporting content, one small step inside the region edge like the header; children are trailing actions. */
     caption?: React.ReactNode;
 };
 declare function PopoverFooter({ className, children, caption, ...props }: PopoverFooterProps): React.JSX.Element;

package/dist/components/base/popover/popover.recipes.d.ts

@@ -1,4 +1,4 @@
-import { type RowDensity } from '../../../lib/row-recipes';
+import type { RowDensity } from '../../../lib/row-recipes';
 /** Shared anchored-surface chrome; Menu and Popover retain their own accessible behavior. */
 /**
  * One width scale for anchored surfaces. Menus, pickers and popovers choose a
@@ -15,18 +15,22 @@ export declare const popoverWidthRecipes: {
     readonly menuMin: "min-w-40";
 };
 export declare const popoverRecipes: {
-    readonly surface: "box-border max-w-[calc(100vw-2rem)] rounded-radius border border-border bg-popover text-popover-foreground shadow-md ring-0";
+    readonly surface: "box-border max-w-[calc(100vw-2rem)] rounded-surface border border-border bg-popover text-popover-foreground shadow-md ring-0";
     readonly display: "p-surface";
-    readonly menu: "p-surface-xs";
-    readonly menuRegion: "px-surface-xs py-space-md";
+    readonly displayCompact: "p-surface-xs";
+    readonly menu: "p-space-md";
+    readonly menuInline: "px-space-md";
+    readonly menuRegion: "px-space-md py-space-md";
+    readonly menuCopyInset: "px-space-xs";
+    readonly menuSearch: "[&_[data-slot=command-input-wrapper]]:p-space-md";
     readonly separator: "mx-0 my-space-xs h-px w-full shrink-0 bg-border/60";
-    readonly row: "box-border min-h-control rounded-inner px-row-x gap-space-sm font-medium leading-tight";
+    readonly row: "box-border min-h-control rounded-radius px-row-x gap-space-sm font-medium leading-tight";
 };
 export type PopoverContentType = 'display' | 'menu';
 /** One surface inset vocabulary for Popover, Command and their collections. */
 export declare const surfaceInsetClasses: {
     readonly default: "p-surface";
-    readonly compact: "p-surface-xs";
+    readonly compact: "p-space-md";
     readonly flush: "p-0";
 };
 /** Collection density changes vertical rhythm; inline room and primary text stay stable. */

package/dist/components/base/sheet/sheet.d.ts

@@ -23,6 +23,8 @@ export declare const SheetClose: React.ForwardRefExoticComponent<Omit<import("@b
 export declare const SheetContent: React.ForwardRefExoticComponent<Omit<import("@base-ui/react").AlertDialogPopupProps & {
     side?: "top" | "right" | "bottom" | "left";
     showCloseButton?: boolean;
+    forceRenderBackdrop?: boolean;
+    backdropClassName?: string;
 } & {
     container?: import("../../../lib/theme-scope").ThemePortalContainer;
 }, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/components/base/sidebar/index.d.ts

@@ -1,4 +1,4 @@
-export { Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, defaultSidebarStrings, type SidebarProps, type SidebarInputProps, type SidebarMenuBadgeProps, type SidebarMenuButtonProps, type SidebarMenuDensity, type SidebarMenuProps, type SidebarMenuSkeletonProps, type SidebarMenuSubButtonProps, type SidebarProviderProps, type SidebarStrings, } from './sidebar';
+export { Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRegion, SidebarRail, SidebarSeparator, SidebarTrigger, defaultSidebarStrings, type SidebarProps, type SidebarInputProps, type SidebarMenuBadgeProps, type SidebarMenuButtonProps, type SidebarMenuDensity, type SidebarMenuProps, type SidebarMenuSkeletonProps, type SidebarMenuSubButtonProps, type SidebarProviderProps, type SidebarRegionProps, type SidebarPanelId, type SidebarPresentation, type SidebarStrings, } from './sidebar';
 /**
  * @deprecated Use `useLayoutSidebar` from `themelia-react-ui/layout/sidebar`.
  * This vendored compatibility re-export remains available through 1.x.

package/dist/components/base/sidebar/sidebar.d.ts

@@ -1,11 +1,12 @@
 /**
  * base/sidebar — tokenized wrapper around the shadcn `Sidebar` compound component.
  *
- * The shadcn source stays untouched. This layer applies the package shell,
+ * The internal Base UI owner supplies shared state. This layer applies the package shell,
  * density, spacing, typography, focus, and stable DOM-hook contracts while
  * preserving every compound part and polymorphic `render` seam.
  */
 import * as React from 'react';
+import { type SidebarPanelId, type SidebarPresentation, type SidebarStateProps } from '../../ui/sidebar-state';
 import { SidebarContent as SidebarContentPrimitive, SidebarFooter as SidebarFooterPrimitive, SidebarGroup as SidebarGroupPrimitive, SidebarGroupAction as SidebarGroupActionPrimitive, SidebarGroupContent as SidebarGroupContentPrimitive, SidebarGroupLabel as SidebarGroupLabelPrimitive, SidebarHeader as SidebarHeaderPrimitive, SidebarInput as SidebarInputPrimitive, SidebarInset as SidebarInsetPrimitive, SidebarMenu as SidebarMenuPrimitive, SidebarMenuAction as SidebarMenuActionPrimitive, SidebarMenuBadge as SidebarMenuBadgePrimitive, SidebarMenuButton as SidebarMenuButtonPrimitive, SidebarMenuItem as SidebarMenuItemPrimitive, SidebarMenuSub as SidebarMenuSubPrimitive, SidebarMenuSubButton as SidebarMenuSubButtonPrimitive, SidebarMenuSubItem as SidebarMenuSubItemPrimitive, SidebarRail as SidebarRailPrimitive, SidebarSeparator as SidebarSeparatorPrimitive, SidebarTrigger as SidebarTriggerPrimitive, useSidebar as useSidebarPrimitive } from '../../ui/sidebar';
 import type { ComponentScale } from '../../../lib/component-vocabulary';
 import { type StringsProp } from '../../../lib/strings';
@@ -15,6 +16,10 @@ export interface SidebarStrings {
 }
 export declare const defaultSidebarStrings: SidebarStrings;
 export interface SidebarProps extends React.ComponentProps<'div'> {
+    /** Explicit state identity; otherwise inherits the nearest shell region. */
+    panelId?: SidebarPanelId;
+    /** Desktop canvas treatment. Drawers always retain their opaque sidebar surface. */
+    surface?: 'default' | 'transparent';
     /** Edge where the desktop rail and mobile sheet are anchored. */
     side?: 'left' | 'right';
     /** Surface treatment and inset behavior for the desktop shell. */
@@ -27,7 +32,7 @@ export interface SidebarProps extends React.ComponentProps<'div'> {
     surfaceClassName?: string;
     /** Classes for the responsive positioning root. */
     rootClassName?: string;
-    /** Copy for the visually hidden mobile sheet title and description. */
+    /** Copy for the mobile drawer heading and accessible description. */
     strings?: StringsProp<SidebarStrings>;
 }
 type SidebarContentProps = React.ComponentProps<typeof SidebarContentPrimitive>;
@@ -83,7 +88,7 @@ export interface SidebarMenuSubButtonProps extends Omit<React.ComponentProps<typ
     active?: boolean;
 }
 type SidebarMenuSubItemProps = React.ComponentProps<typeof SidebarMenuSubItemPrimitive>;
-export interface SidebarProviderProps extends React.ComponentProps<'div'> {
+export interface SidebarProviderProps extends React.ComponentProps<'div'>, SidebarStateProps {
     /** Use the provider width for drawers in embedded workspaces; viewport remains the default. */
     adaptTo?: 'viewport' | 'container';
     /** Initial expanded state for uncontrolled sidebars. @default true */
@@ -105,8 +110,24 @@ type SidebarRailProps = React.ComponentProps<typeof SidebarRailPrimitive>;
 type SidebarSeparatorProps = React.ComponentProps<typeof SidebarSeparatorPrimitive>;
 type SidebarTriggerProps = React.ComponentProps<typeof SidebarTriggerPrimitive>;
 declare function SidebarProvider({ className, style, menuDensity, ...props }: SidebarProviderProps): React.JSX.Element;
+export interface SidebarRegionProps extends Omit<React.ComponentProps<'div'>, 'ref'> {
+    /** Ref to the semantic aside boundary. */
+    ref?: React.Ref<HTMLElement>;
+    /** Named desktop/drawer state and descendant scope owned by this region. */
+    panelId: SidebarPanelId;
+    /** Minimum available width for docking; primary/secondary/aside default to 768/1024/1440. Zero stays docked. */
+    dockAt?: number;
+    /** Persistent region geometry, separate from docked/drawer presentation. */
+    presentation?: 'panel' | 'rail';
+    /** Physical edge inherited by the scoped Sidebar and its drawer. @default 'left' */
+    side?: 'left' | 'right';
+    /** Expanded CSS length; defaults to --shell-sidebar-width. Rail widths derive from existing density roots. */
+    width?: string;
+}
+/** A named state and width boundary. Shells can also use static content without a provider. */
+declare function SidebarRegion({ panelId, dockAt, presentation, side, width, className, style, ref: forwardedRef, children, ...props }: SidebarRegionProps): React.JSX.Element;
 /** Tokenized responsive sidebar shell with contained and viewport-fixed modes. */
-declare function Sidebar({ side, variant, collapsible, contained, className, surfaceClassName, rootClassName, children, dir, strings: stringsProp, ...props }: SidebarProps): React.JSX.Element;
+declare function Sidebar(props: SidebarProps): React.JSX.Element;
 declare function SidebarHeader({ className, ...props }: SidebarHeaderProps): React.JSX.Element;
 declare function SidebarFooter({ className, ...props }: SidebarFooterProps): React.JSX.Element;
 declare function SidebarContent({ className, ...props }: SidebarContentProps): React.JSX.Element;
@@ -128,8 +149,9 @@ declare function SidebarTrigger({ className, ...props }: SidebarTriggerProps): R
 declare function SidebarMenuButton({ className, render, size, tooltip, children, active, ...props }: SidebarMenuButtonProps): React.JSX.Element;
 declare function SidebarMenuSubButton({ className, children, active, ...props }: SidebarMenuSubButtonProps): React.JSX.Element;
 declare function SidebarGroupLabel({ className, children, ...props }: SidebarGroupLabelProps): React.JSX.Element;
-export { Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, };
+export { Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRegion, SidebarRail, SidebarSeparator, SidebarTrigger, };
 /** Internal bridge for the layout layer; not part of the base package entrypoint. */
 export declare const useBaseSidebarContext: typeof useSidebarPrimitive;
 /** Internal density bridge for composed navigation; not a base entrypoint export. */
 export declare function useBaseSidebarMenuDensity(): SidebarMenuDensity | undefined;
+export type { SidebarPanelId, SidebarPresentation };

package/dist/components/base/structure/composition.recipes.d.ts

@@ -0,0 +1,17 @@
+/** Private relationship defaults. Generic Stack/Grid retain their own defaults;
+ * surface regions and collection rows keep their independent recipe owners. */
+export declare const compositionRhythm: {
+    readonly commands: "md";
+    readonly compactActions: "xs";
+    readonly related: "xl";
+    readonly subjects: "2xl";
+    readonly page: "3xl";
+};
+/** Native layout owners use the same vocabulary as Stack/Grid. */
+export declare const compositionClasses: {
+    readonly commands: string;
+    readonly compactActions: string;
+    readonly related: string;
+    readonly subjects: string;
+    readonly page: string;
+};

package/dist/components/base/text-inputs/hooks/use-form-field-state.d.ts

@@ -1,6 +1,11 @@
+import { type RefObject } from 'react';
 export interface UseFormFieldStateOptions {
     /** Controlled value from parent */
-    controlledValue?: string;
+    controlledValue?: string | null;
+    /** Presence of the value prop, including an explicitly empty value. */
+    hasControlledValue?: boolean;
+    /** Native field whose value may be assigned by registration or reset. */
+    nativeRef?: RefObject<HTMLInputElement | HTMLTextAreaElement | null>;
     /** Default value for uncontrolled mode */
     defaultValue?: string;
     /** Maximum character length */
@@ -45,4 +50,4 @@ export interface UseFormFieldStateReturn {
  * - React Hook Form compatibility detection
  * - ID generation
  */
-export declare function useFormFieldState({ controlledValue, defaultValue, maxLength, showCharacterCount, providedId, idPrefix, hasOnChange, }: UseFormFieldStateOptions): UseFormFieldStateReturn;
+export declare function useFormFieldState({ controlledValue, hasControlledValue, nativeRef, defaultValue, maxLength, showCharacterCount, providedId, idPrefix, hasOnChange, }: UseFormFieldStateOptions): UseFormFieldStateReturn;

package/dist/components/base/text-inputs/input.d.ts

@@ -7,7 +7,7 @@ export interface InputStrings {
     clear: string;
 }
 export declare const defaultInputStrings: InputStrings;
-export interface InputProps extends Omit<React.ComponentProps<'input'>, 'onChange' | 'size'> {
+export interface InputProps extends Omit<React.ComponentProps<'input'>, 'onChange' | 'size' | 'value'> {
     /** Decorative or semantic icon rendered before the value. */
     startIcon?: LucideIcon;
     /** Decorative or semantic icon rendered after the value. */
@@ -34,8 +34,10 @@ export interface InputProps extends Omit<React.ComponentProps<'input'>, 'onChang
     size?: FormControlSize;
     /** Native-style value callback for the controlled raw string. */
     onChange?: (e: React.ChangeEvent<HTMLInputElement>) => void;
+    /** Raw string callback, emitted alongside the native change event. */
+    onValueChange?: (value: string) => void;
     /** Controlled raw string value. */
-    value?: string;
+    value?: string | null;
     /** Initial raw string value for uncontrolled usage. */
     defaultValue?: string;
     /** Accessible copy overrides for input-owned actions. */

package/dist/components/base/text-inputs/textarea.d.ts

@@ -5,7 +5,7 @@ export interface TextareaStrings {
     clear: string;
 }
 export declare const defaultTextareaStrings: TextareaStrings;
-export interface TextareaProps extends Omit<React.ComponentProps<'textarea'>, 'onChange'> {
+export interface TextareaProps extends Omit<React.ComponentProps<'textarea'>, 'onChange' | 'value'> {
     /** Overrides the character-count and clear copy. */
     strings?: StringsProp<TextareaStrings>;
     /** Character cap, also used as the denominator of the count. */
@@ -28,8 +28,10 @@ export interface TextareaProps extends Omit<React.ComponentProps<'textarea'>, 'o
     /** Height at which the field stops growing and starts scrolling. */
     maxRows?: number;
     onChange?: (e: React.ChangeEvent<HTMLTextAreaElement>) => void;
+    /** Raw string callback, emitted alongside the native change event. */
+    onValueChange?: (value: string) => void;
     /** Current text. Controlled. */
-    value?: string;
+    value?: string | null;
     /** Initial text for uncontrolled use. */
     defaultValue?: string;
 }

package/dist/components/base/toaster/index.d.ts

@@ -1 +1,2 @@
 export { Toaster, type ToasterProps } from './toaster';
+export { toast } from 'sonner';