@riverbankcms/sdk 0.146.0 → 0.148.0

package/dist/_dts/theme-core/src/header/effectiveNavLinkStyle.d.ts

@@ -0,0 +1,17 @@
+import type { ThemeHeader } from '../schema';
+import { type NavLinkContrastTreatment, type NavLinkStyle } from '../navigation/types';
+import { type SurfaceForegroundInput } from '../surfaces';
+import { type ForegroundHoverInput } from '../surfaces/foregroundInteraction';
+export declare function effectiveHeaderNavLinkStyle(header: Partial<ThemeHeader> | undefined, contrastTreatment?: NavLinkContrastTreatment | null, navTextSize?: NavLinkStyle['textSize'] | null): NavLinkStyle | null;
+export declare function headerForegroundCandidates(header: Partial<ThemeHeader> | undefined): {
+    text?: undefined;
+    link?: undefined;
+    linkHover?: undefined;
+} | {
+    text: string | null | undefined;
+    link: string | null | undefined;
+    linkHover: import("../../../blocks/src/index").ThemeColorToken | null;
+};
+export declare function headerLeafTextColor(header: Partial<ThemeHeader> | undefined): NonNullable<ThemeHeader['textColor']>;
+/** Transparent chrome must reset the whole contract on its own root. */
+export declare function transparentHeaderForegroundInput(header: Partial<ThemeHeader> | undefined, palette: ForegroundHoverInput['palette']): SurfaceForegroundInput;

package/dist/_dts/theme-core/src/header/generateHeaderLogoStyles.d.ts

@@ -0,0 +1,15 @@
+import type { LogoStyle, Theme } from '../schema';
+import type { TokenResolver } from '../tokens/resolver';
+import type { NavLinkStyle } from '../navigation/types';
+type HeaderLogoStyleInput = Readonly<{
+    logo: LogoStyle | undefined;
+    themeId: string;
+    tokens: TokenResolver;
+    theme: Theme;
+    textColor?: string | null;
+    fallbackTextColor?: string | null;
+    contrastTreatment?: NavLinkStyle['contrastTreatment'];
+    useSurfaceTextColor: boolean;
+}>;
+export declare function generateHeaderLogoStyles(input: HeaderLogoStyleInput): string;
+export {};

package/dist/_dts/theme-core/src/header/generateHeaderNavLinkStyles.d.ts

@@ -0,0 +1,4 @@
+import type { Theme, ThemeHeader } from '../schema';
+import type { TokenResolver } from '../tokens/resolver';
+import type { NavLinkContrastTreatment, NavLinkStyle } from '../navigation/types';
+export declare function generateHeaderNavLinkStyles(header: ThemeHeader, themeId: string, tokens: TokenResolver, theme: Theme, contrastTreatment: NavLinkContrastTreatment | null, navTextSize: NavLinkStyle['textSize'] | null): string;

package/dist/_dts/theme-core/src/header/index.d.ts

@@ -1 +1,4 @@
 export { generateHeaderCss } from './generateHeaderCss';
+export { headerRootPaint, type HeaderRootPaint } from './rootPaint';
+export { effectiveHeaderNavLinkStyle, headerForegroundCandidates, headerLeafTextColor, transparentHeaderForegroundInput, } from './effectiveNavLinkStyle';
+export { readOpeningForegroundProjection } from './openingForegroundProjection';

package/dist/_dts/theme-core/src/header/legacyNavLinkStyle.d.ts

@@ -1,3 +1,3 @@
 import type { NavLinkContrastTreatment, NavLinkStyle } from '../navigation/types';
 import type { ThemeHeader } from '../schema';
-export declare function buildLegacyHeaderNavLinkStyle(header: ThemeHeader, contrastTreatment: NavLinkContrastTreatment | null, navTextSize: NavLinkStyle['textSize'] | null): NavLinkStyle | null;
+export declare function buildLegacyHeaderNavLinkStyle(header: Partial<ThemeHeader>, contrastTreatment: NavLinkContrastTreatment | null, navTextSize: NavLinkStyle['textSize'] | null): NavLinkStyle | null;

package/dist/_dts/theme-core/src/header/openingForegroundProjection.d.ts

@@ -0,0 +1,7 @@
+import type { ThemeHeader } from '../schema';
+import type { ResolvedSurfaceForeground } from '../surfaces';
+type OpeningForeground = ResolvedSurfaceForeground;
+/** Page-scoped render data. It is deliberately absent from the persisted theme schema. */
+export declare function withOpeningForegroundProjection(header: ThemeHeader, foreground: OpeningForeground): ThemeHeader;
+export declare function readOpeningForegroundProjection(header: Partial<ThemeHeader> | undefined): OpeningForeground | null;
+export {};

package/dist/_dts/theme-core/src/header/rootPaint.d.ts

@@ -0,0 +1,4 @@
+import type { ThemeHeader } from '../schema';
+export type HeaderRootPaint = 'own-surface' | 'contained-nav' | 'overlay';
+/** The nav container takes precedence when a floating header also has one. */
+export declare function headerRootPaint(header: Partial<ThemeHeader> | null | undefined): HeaderRootPaint;

package/dist/_dts/theme-core/src/navigation/effectPolicy.d.ts

@@ -0,0 +1,38 @@
+type NavEffectPolicy = 'paired-hover' | 'text-colour' | 'underline' | 'other';
+/** Every registered effect has one meaning for surface-owned nav hover. */
+export declare const NAV_EFFECT_POLICIES: {
+    readonly 'darken-background': "other";
+    readonly 'lighten-background': "other";
+    readonly 'fade-background': "other";
+    readonly 'opacity-reduce': "other";
+    readonly 'animated-gradient': "other";
+    readonly 'background-on-hover': "paired-hover";
+    readonly 'background-on-hover-alpha': "paired-hover";
+    readonly 'border-glow': "other";
+    readonly 'drop-shadow': "other";
+    readonly 'inner-shadow': "other";
+    readonly 'neumorphic-shadow': "other";
+    readonly 'outer-glow': "other";
+    readonly 'retro-3d-shadow': "other";
+    readonly 'scale-up': "other";
+    readonly 'scale-down': "other";
+    readonly lift: "other";
+    readonly 'press-down': "other";
+    readonly pop: "other";
+    readonly 'aurora-glow': "other";
+    readonly 'cosmic-stardust': "other";
+    readonly 'gradient-border-fill': "other";
+    readonly 'animated-gradient-border-fill': "other";
+    readonly 'border-bottom-grow': "other";
+    readonly 'gradient-text': "other";
+    readonly 'text-color-change': "text-colour";
+    readonly 'border-color-change': "other";
+    readonly 'sketchy-border': "other";
+    readonly 'pulse-animation': "other";
+    readonly 'nav-underline': "underline";
+    readonly 'nav-frosted-base': "other";
+    readonly 'nav-frosted-hover': "other";
+    readonly 'nav-frosted-active': "other";
+};
+export declare function navEffectPolicy(effectId: string): NavEffectPolicy | null;
+export {};

package/dist/_dts/theme-core/src/navigation/generateNavLinkCSS.d.ts

@@ -18,6 +18,10 @@ export interface GenerateNavLinkCSSOptions {
     style: NavLinkStyle;
     /** CSS class name for the nav link (e.g., 'header-nav-link', 'footer-nav-link') */
     className: string;
+    /** Text links whose colours come from the owning background surface. */
+    surfaceDependent?: boolean;
+    /** Use the owning surface at rest while preserving the style's painted hover. */
+    surfaceRestingColor?: boolean;
 }
 /**
  * Generate complete CSS for nav links from a NavLinkStyle configuration

package/dist/_dts/theme-core/src/navigation/types.d.ts

@@ -4,6 +4,7 @@
  * Schema and types for composable nav link styling used by header and footer.
  */
 import { z } from 'zod';
+import { type ThemeColorToken } from '../tokens/themeColorTokens';
 /**
  * Padding preset options for nav links
  */
@@ -146,6 +147,9 @@ export type NavLinkTextSize = z.infer<typeof navLinkTextSizeSchema>;
 export type NavLinkLetterSpacing = z.infer<typeof navLinkLetterSpacingSchema>;
 export type NavLinkContrastTreatment = z.infer<typeof navLinkContrastTreatmentSchema>;
 export type NavLinkStyle = z.infer<typeof navLinkStyleSchema>;
+export declare function navLinkHoverColorCandidate(style: Pick<NavLinkStyle, 'hoverColorToken' | 'effects'> | null | undefined): ThemeColorToken | null;
+export declare function navLinkOwnsHoverForeground(style: Pick<NavLinkStyle, 'effects'> | null | undefined): boolean;
+export declare function navLinkOwnsUnderline(style: Pick<NavLinkStyle, 'effects'> | null | undefined): boolean;
 /**
  * Padding values for nav link padding presets
  */

package/dist/_dts/theme-core/src/site-styles/accessibleSurfaces.d.ts

@@ -3,7 +3,7 @@ import type { SurfaceForegroundRole } from '../surfaces/foregroundRoles';
 import type { SiteStyleSurfaceIntent } from './types';
 export type AccessibleColorSurfaceIntent = Exclude<SiteStyleSurfaceIntent, 'hero-image'>;
 export type ContrastPolicy = 'body-aa' | 'large-text-aa' | 'decorative';
-export type ForegroundRole = SurfaceForegroundRole;
+export type ForegroundRole = Exclude<SurfaceForegroundRole, 'linkHover'>;
 export type AccessibleSurfaceToken = string & {
     readonly __brand: 'AccessibleSurfaceToken';
 };

package/dist/_dts/theme-core/src/site-styles/designState.d.ts

@@ -85,10 +85,10 @@ export type PageStyleAuthoritySummary<TBlockId extends string = DesignBlockId> =
 export declare const styleAuthoritySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"theme-v2">;
     source: z.ZodEnum<{
+        sdk: "sdk";
         generated: "generated";
         user: "user";
         admin: "admin";
-        sdk: "sdk";
     }>;
     siteStyleId: z.ZodPipe<z.ZodString, z.ZodTransform<SiteStyleId, string>>;
     templateId: z.ZodPipe<z.ZodString, z.ZodTransform<DesignSystemTemplateId, string>>;
@@ -116,10 +116,10 @@ export declare const blockRuntimeStyleAuthoritySchema: z.ZodObject<{
     authority: z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"theme-v2">;
         source: z.ZodEnum<{
+            sdk: "sdk";
             generated: "generated";
             user: "user";
             admin: "admin";
-            sdk: "sdk";
         }>;
         siteStyleId: z.ZodPipe<z.ZodString, z.ZodTransform<SiteStyleId, string>>;
         templateId: z.ZodPipe<z.ZodString, z.ZodTransform<DesignSystemTemplateId, string>>;

package/dist/_dts/theme-core/src/surfaces/foregroundContract.d.ts

@@ -1,13 +1,17 @@
 import { type SurfaceForegroundInput, type SurfaceForegroundRole, type SurfaceForegrounds } from './foregroundRoles';
+import type { ThemeColorToken } from '../tokens/themeColorTokens';
+import type { ResolvedSurfaceForeground } from './resolveSurfaceForeground';
 export declare const SURFACE_FOREGROUND_CSS_VARS: {
     readonly text: "--rb-surface-text-color";
     readonly heading: "--rb-surface-heading-color";
     readonly link: "--rb-surface-link-color";
+    readonly linkHover: "--rb-surface-link-hover-color";
     readonly supporting: "--rb-surface-supporting-color";
 };
 export type SurfaceForegroundCssVariable = (typeof SURFACE_FOREGROUND_CSS_VARS)[SurfaceForegroundRole];
 export type SurfaceForegroundStyle = Readonly<{
     color: string;
+    '--rb-surface-link-hover-decoration': string;
 } & Record<SurfaceForegroundCssVariable, string>>;
 export declare const DEFAULT_SURFACE_TEXT_COLOR = "rgb(var(--tb-text, 17 24 39))";
 export declare const DEFAULT_SURFACE_LINK_COLOR = "rgb(var(--tb-primary, var(--tb-text, 17 24 39)))";
@@ -17,3 +21,6 @@ export declare function surfaceForegroundValue(role: SurfaceForegroundRole, outs
 export declare function surfaceForegroundValueWithOpacity(role: SurfaceForegroundRole, opacityPercent: number): string;
 export declare function surfaceForegroundStyle(input: SurfaceForegroundInput): SurfaceForegroundStyle;
 export declare function surfaceForegroundDeclarations(input: SurfaceForegroundInput): readonly string[];
+export declare function surfaceForegroundInputFromResolved(foreground: Extract<ResolvedSurfaceForeground, {
+    kind: 'known';
+}>, color: (token: ThemeColorToken) => string): SurfaceForegroundInput;

package/dist/_dts/theme-core/src/surfaces/foregroundInteraction.d.ts

@@ -46,32 +46,39 @@ export declare const FOREGROUND_HOVER_OPACITY_PERCENT = 85;
  * should leave hover alone rather than guess.
  */
 export declare function deriveForegroundHoverToken(restingToken: ThemeColorToken): ThemeColorToken | null;
+/**
+ * The extreme backdrop a glass tone can present, whatever page content happens
+ * to be underneath it.
+ *
+ * A 60% tint clamps the composite into a known band, which is what makes a
+ * conservative check possible at compile time even though the content passing
+ * under a sticky header is not knowable. For a dark glass the composite is
+ * lightest over white; for a light glass it is darkest over black. Those are
+ * the two ends that a foreground has to survive.
+ */
+export declare function worstCaseGlassBackdrop(tone: 'light' | 'dark'): string;
 /** Flatten `foreground` at `alpha` over `background` into an opaque hex. */
 export declare function compositeHex(foreground: string, background: string, alpha: number): string;
-export type ForegroundHoverPlan = 
-/** Soften the resting colour; the derived token clears the conservative bound. */
-Readonly<{
-    kind: 'softened';
+export type ForegroundHoverPlan = Readonly<{
+    kind: 'candidate' | 'softened';
     token: ThemeColorToken;
-}>
-/**
- * Keep the resting colour. Softening it would drop below the ordinary-text
- * ratio somewhere the glass can reach, so the hover affordance has to come
- * from something other than colour.
- */
- | Readonly<{
+    decoration: 'initial';
+}> | Readonly<{
     kind: 'resting';
+    token: ThemeColorToken;
+    decoration: 'underline';
+}>;
+export type ForegroundHoverInput = Readonly<{
+    restingToken: ThemeColorToken;
+    candidate?: ThemeColorToken | null;
+    palette: Readonly<Record<string, string>>;
+    /** Null means the complete backdrop cannot be measured. */
+    backdrops: readonly string[] | null;
 }>;
 /**
- * Decide whether the resting foreground can safely be softened for hover.
- *
- * `glassTone` is the scroll treatment's compiled tone, or `null` when the style
- * has no glass. Without one there is no bound on what the header can end up
- * over, so this declines to soften rather than guess.
- *
- * The light-glass end cannot be satisfied by any softening: against `#999999`
- * a dark resting foreground is already close to the 4.5:1 line, so every step
- * away from it fails. That is why this returns a plan rather than a colour —
- * the caller has to have a non-colour affordance to fall back on.
+ * Prefer an authored hover that survives every measured backdrop, then a
+ * checked softening of the resting colour. A null backdrop set represents a
+ * trusted treatment: only an explicit authored hover may change the colour.
+ * When neither option works, retain the resting colour and underline it.
  */
-export declare function planForegroundHover(restingToken: ThemeColorToken, restingHex: string | null, glassTone: 'light' | 'dark' | null): ForegroundHoverPlan;
+export declare function planForegroundHover(input: ForegroundHoverInput): ForegroundHoverPlan;

package/dist/_dts/theme-core/src/surfaces/foregroundRoles.d.ts

@@ -1,9 +1,17 @@
-export declare const SURFACE_FOREGROUND_ROLES: readonly ["text", "heading", "link", "supporting"];
+export declare const SURFACE_FOREGROUND_ROLES: readonly ["text", "heading", "link", "linkHover", "supporting"];
 export type SurfaceForegroundRole = (typeof SURFACE_FOREGROUND_ROLES)[number];
 export type SurfaceForegrounds = Readonly<Record<SurfaceForegroundRole, string>>;
-export type SurfaceForegroundInput = Readonly<{
+type SurfaceForegroundBaseInput = Readonly<{
     text: string;
     heading?: string;
     link?: string;
     supporting?: string;
 }>;
+export type SurfaceForegroundInput = SurfaceForegroundBaseInput & (Readonly<{
+    linkHover?: never;
+    hoverDecoration?: never;
+}> | Readonly<{
+    linkHover: string;
+    hoverDecoration: 'underline' | 'initial';
+}>);
+export {};

package/dist/_dts/theme-core/src/surfaces/resolveSurfaceForeground.d.ts

@@ -4,10 +4,18 @@ export { ORDINARY_TEXT_MIN_CONTRAST_RATIO } from '../palette/utils/contrast';
 export type ResolvedSurfaceForegroundTokens = Readonly<Record<SurfaceForegroundRole, ThemeColorToken>>;
 export type ResolvedSurfaceForeground = Readonly<{
     kind: 'known';
+    provenance: SurfaceForegroundProvenance;
     roles: ResolvedSurfaceForegroundTokens;
+    hoverDecoration: 'underline' | 'initial';
 }> | Readonly<{
     kind: 'unknown';
 }>;
+export type SurfaceForegroundProvenance = Readonly<{
+    kind: 'measured';
+    backdropHex: string;
+}> | Readonly<{
+    kind: 'trusted-treatment';
+}>;
 export type SurfaceForegroundBackground = Readonly<{
     type: 'color' | 'gradient' | 'image' | 'video';
     color?: string | null;
@@ -20,6 +28,7 @@ export type SurfaceForegroundCandidates = Readonly<{
     text?: string | null;
     heading?: string | null;
     link?: string | null;
+    linkHover?: string | null;
     supporting?: string | null;
 }>;
 export type SurfaceForegroundResolutionOptions = Readonly<{

package/dist/_dts/theme-core/src/utils/cssDeclarations.d.ts

@@ -0,0 +1,2 @@
+/** Render CSS declarations whether callers provide terminators or fragments. */
+export declare function renderCssDeclarations(declarations: readonly string[]): string;

package/dist/_dts/ui/src/badge.d.ts

@@ -2,8 +2,9 @@ import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
 declare const badgeVariants: (props?: ({
     variant?: "success" | "default" | "warning" | "secondary" | "destructive" | "outline" | null | undefined;
+    dot?: boolean | "bare" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export interface BadgeProps extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof badgeVariants> {
 }
-declare function Badge({ className, variant, ...props }: BadgeProps): React.JSX.Element;
+declare function Badge({ className, variant, dot, ...props }: BadgeProps): React.JSX.Element;
 export { Badge, badgeVariants };

package/dist/_dts/ui/src/button.d.ts

@@ -1,7 +1,7 @@
 import { type VariantProps } from 'class-variance-authority';
 import * as React from 'react';
 declare const buttonVariants: (props?: ({
-    variant?: "link" | "default" | "secondary" | "destructive" | "outline" | "ghost" | "onDark" | "onDarkOutline" | "heroGlass" | null | undefined;
+    variant?: "link" | "default" | "secondary" | "destructive" | "outline" | "ghost" | "onDark" | "heroGlass" | null | undefined;
     size?: "default" | "sm" | "lg" | "icon" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {

package/dist/_dts/ui/src/combobox-keys.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What a key press means to a `Combobox`, from the trigger or from its search
+ * input. Pure tables, so the component only has to carry an intent out.
+ */
+export type ComboboxKeyIntent = Readonly<{
+    tag: 'open';
+    fallback: 'first' | 'last';
+}> | Readonly<{
+    tag: 'move';
+    by: 1 | -1;
+}> | Readonly<{
+    tag: 'choose';
+}> | Readonly<{
+    tag: 'close';
+}> | Readonly<{
+    tag: 'none';
+}>;
+export type ComboboxKeyResult = Readonly<{
+    intent: ComboboxKeyIntent;
+    preventDefault: boolean;
+}>;
+export declare function triggerKeyIntent(key: string, open: boolean, search: boolean): ComboboxKeyResult;
+export declare function searchKeyIntent(key: string): ComboboxKeyResult;

package/dist/_dts/ui/src/combobox-rows.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The rows a `Combobox` list shows for a search: an optional "none" row, the
+ * matching items in the order given, and an optional "Create …" row. Pure, so
+ * the list and its keyboard handling agree on one sequence of rows.
+ */
+export type ComboboxRowItem = Readonly<{
+    id: string;
+    label: string;
+    searchText?: string;
+}>;
+export type ComboboxRow<TEntry extends ComboboxRowItem> = Readonly<{
+    kind: 'none';
+    id: string;
+}> | Readonly<{
+    kind: 'item';
+    id: string;
+    entry: TEntry;
+}> | Readonly<{
+    kind: 'create';
+    id: string;
+    name: string;
+}>;
+export declare const COMBOBOX_NONE_ROW_ID = "__none__";
+export declare const COMBOBOX_CREATE_ROW_ID = "__create__";
+/** Trims and collapses inner whitespace, so "  Morning   yoga " is "Morning yoga". */
+export declare function normalizeComboboxQuery(query: string): string;
+export declare function buildComboboxRows<TEntry extends ComboboxRowItem>(input: Readonly<{
+    items: readonly TEntry[];
+    query: string;
+    /** Search off means every item shows and nothing can be created. */
+    search: boolean;
+    hasNoneOption: boolean;
+    canCreate: boolean;
+}>): ComboboxRow<TEntry>[];

package/dist/_dts/ui/src/combobox.d.ts

@@ -5,13 +5,31 @@ export type ComboboxItem<T = unknown> = Readonly<{
     searchText?: string;
     item: T;
 }>;
+export type ComboboxCreateResult<T = unknown> = Readonly<{
+    ok: true;
+    item: ComboboxItem<T>;
+}> | Readonly<{
+    ok: false;
+    message: string;
+}>;
+/**
+ * Offers "Create …" for a search that no item is named exactly. The created
+ * item is selected as soon as `onCreate` resolves with it; a failure keeps
+ * the list open and shows the message under the search.
+ */
+export type ComboboxCreate<T = unknown> = Readonly<{
+    label: (name: string) => string;
+    onCreate: (name: string) => Promise<ComboboxCreateResult<T>>;
+}>;
 export type ComboboxProps<T = unknown> = Readonly<{
     items: readonly ComboboxItem<T>[];
     value?: string;
     onSelect: (item: ComboboxItem<T> | undefined) => void;
     id?: string;
     'aria-describedby'?: string;
+    'aria-invalid'?: boolean;
     searchInputAriaLabel?: string;
+    searchPlaceholder?: string;
     placeholder?: string;
     emptyMessage?: string;
     clearLabel?: string;
@@ -19,6 +37,13 @@ export type ComboboxProps<T = unknown> = Readonly<{
     className?: string;
     disabled?: boolean;
     renderItem?: (entry: ComboboxItem<T>, selected: boolean) => ReactNode;
+    /** Shown before the label in the list and on the field, such as a colour swatch. */
+    renderLeading?: (entry: ComboboxItem<T>) => ReactNode;
     showClear?: boolean;
+    /** A first row that clears the value, labelled like "No category". */
+    noneOption?: Readonly<{
+        label: string;
+    }>;
+    create?: ComboboxCreate<T>;
 }>;
-export declare function Combobox<T = unknown>({ items, value, onSelect, id, 'aria-describedby': ariaDescribedby, searchInputAriaLabel, placeholder, emptyMessage, clearLabel, search, className, disabled, renderItem, showClear, }: ComboboxProps<T>): import("react").JSX.Element;
+export declare function Combobox<T = unknown>(props: ComboboxProps<T>): import("react").JSX.Element;

package/dist/_dts/ui/src/date-picker.d.ts

@@ -1,16 +1,13 @@
-import { type ReactNode, type MouseEventHandler } from 'react';
-import { type ButtonProps } from './button';
-export type DatePickerTriggerButtonProps = Omit<ButtonProps, 'children'> & {
+import { type ReactNode } from 'react';
+import { type FieldTriggerProps } from './field-trigger';
+export type DatePickerTriggerButtonProps = Omit<FieldTriggerProps, 'children' | 'isPlaceholder' | 'leading' | 'trailing'> & {
     selected: boolean;
-    active?: boolean;
     label: ReactNode;
     placeholder: ReactNode;
-    onClick?: MouseEventHandler<HTMLButtonElement>;
 };
-export declare const DatePickerTriggerButton: import("react").ForwardRefExoticComponent<Omit<ButtonProps, "children"> & {
+/** The field that opens a calendar: a `FieldTrigger` led by a calendar icon. */
+export declare const DatePickerTriggerButton: import("react").ForwardRefExoticComponent<Omit<FieldTriggerProps, "children" | "isPlaceholder" | "leading" | "trailing"> & {
     selected: boolean;
-    active?: boolean;
     label: ReactNode;
     placeholder: ReactNode;
-    onClick?: MouseEventHandler<HTMLButtonElement>;
 } & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/_dts/ui/src/editor-item-card.d.ts

@@ -35,6 +35,7 @@ export type EditorItemCardMenu = Readonly<{
     label: string;
     disabled?: boolean;
     ref?: React.Ref<HTMLButtonElement>;
+    onCloseAutoFocus?: (event: Event) => void;
     groups: readonly EditorItemCardMenuGroup[];
 }>;
 export type EditorItemCardActionsProps = Readonly<{

package/dist/_dts/ui/src/field-trigger.d.ts

@@ -0,0 +1,39 @@
+import { type ButtonHTMLAttributes, type ReactNode } from 'react';
+/**
+ * A field that opens a list or calendar: the shared field surface (see
+ * fieldControl.ts), laid out as a button with a value and an icon, so a
+ * picker reads as a field beside the inputs around it rather than as a
+ * button. `SelectTrigger` and `FieldTrigger` both build on it.
+ */
+export declare const fieldTriggerClassName: string;
+export type FieldTriggerProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'> & Readonly<{
+    /** What the field currently shows: the chosen value, or the placeholder. */
+    children: ReactNode;
+    /** True while nothing is chosen, so the text reads as a placeholder. */
+    isPlaceholder?: boolean;
+    /** Shown before the value, such as a calendar icon or a colour swatch. */
+    leading?: ReactNode;
+    /** Pass null to drop the chevron, as the date picker does. */
+    trailing?: ReactNode;
+    /** Kept open-state styling while the popover it controls is showing. */
+    active?: boolean;
+    size?: 'sm' | 'default';
+}>;
+/**
+ * The button that opens a popover picker (a combobox, a multi-select, a date
+ * picker), styled as a field. Spreads the props and ref a Radix trigger passes
+ * through `asChild`.
+ */
+export declare const FieldTrigger: import("react").ForwardRefExoticComponent<Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children"> & Readonly<{
+    /** What the field currently shows: the chosen value, or the placeholder. */
+    children: ReactNode;
+    /** True while nothing is chosen, so the text reads as a placeholder. */
+    isPlaceholder?: boolean;
+    /** Shown before the value, such as a calendar icon or a colour swatch. */
+    leading?: ReactNode;
+    /** Pass null to drop the chevron, as the date picker does. */
+    trailing?: ReactNode;
+    /** Kept open-state styling while the popover it controls is showing. */
+    active?: boolean;
+    size?: "sm" | "default";
+}> & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/_dts/ui/src/fieldControl.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The one field shape, as class strings, so Input, Textarea, SelectTrigger
+ * and the date picker's trigger cannot drift apart. The sizes come from the
+ * `--field-*` tokens in styles/editor-base.css (compact by default, roomy
+ * under `data-field-size="roomy"`); the colours come from the surface's
+ * palette.
+ *
+ * The focus glow and the placeholder are mixed from palette tokens here,
+ * rather than in derived tokens on `:root`, so they follow a surface that
+ * retunes its colours on an inner element.
+ */
+/** Keyboard focus on a field-like control: the focus border and a soft glow in its colour, no outline. */
+export declare const FIELD_FOCUS_CLASS = "focus-visible:outline-none focus-visible:border-field-border-focus focus-visible:shadow-[0_0_0_4px_color-mix(in_srgb,var(--field-border-strong)_18%,transparent)]";
+/** The same focus for a wrapper that draws the border around an inner input (a composite field). */
+export declare const FIELD_FOCUS_WITHIN_CLASS = "focus-within:border-field-border-focus focus-within:shadow-[0_0_0_4px_color-mix(in_srgb,var(--field-border-strong)_18%,transparent)]";
+/**
+ * A native checkbox or radio, for the few places the shared Checkbox and
+ * RadioGroup can't go (native `required`, a radio group split across
+ * sections, packages/ui itself).
+ */
+export declare const NATIVE_CHOICE_CLASS = "size-[1.125rem] shrink-0 cursor-pointer accent-[var(--primary)]";
+/** Border, fill, radius, type, focus glow and the invalid state. No height or padding. */
+export declare const FIELD_SURFACE_CLASS: string;
+/** A single-line control: the surface at the field height. */
+export declare const FIELD_CONTROL_CLASS: string;
+/** A multi-line control: the surface with room to grow. */
+export declare const FIELD_TEXTAREA_CLASS: string;

package/dist/_dts/ui/src/index.d.ts

@@ -13,7 +13,10 @@ export { TabbedScrollableDialogContent, type TabbedScrollableDialogContentProps,
 export { menuHoverInteractionClassName, menuItemInteractionClassName, menuTriggerInteractionClassName, DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuGroup, DropdownMenuPortal, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent, } from './dropdown-menu';
 export { Form, FormField, FormItem, FormLabel, FormControl, FormDescription, FormMessage, useFormField, } from './form';
 export { Input } from './input';
-export { Combobox, type ComboboxItem, type ComboboxProps } from './combobox';
+export { NativeSelect, type NativeSelectProps } from './native-select';
+export { Combobox, type ComboboxCreate, type ComboboxCreateResult, type ComboboxItem, type ComboboxProps, } from './combobox';
+export { FieldTrigger, fieldTriggerClassName, type FieldTriggerProps } from './field-trigger';
+export { normalizeComboboxQuery } from './combobox-rows';
 export { NumberInput, type NumberInputProps } from './number-input';
 export { SearchInput, type SearchInputProps } from './search-input';
 export { MultiSelect, type MultiSelectOption, type MultiSelectProps } from './multi-select';

package/dist/_dts/ui/src/native-select.d.ts

@@ -0,0 +1,8 @@
+import * as React from "react";
+type NativeSelectProps = React.ComponentProps<"select"> & {
+    /** Classes for the positioning wrapper (width, margins, grid placement). */
+    containerClassName?: string;
+};
+/** A native `<select>` in the shared field shape, with a chevron in place of the browser arrow. */
+declare const NativeSelect: React.ForwardRefExoticComponent<Omit<NativeSelectProps, "ref"> & React.RefAttributes<HTMLSelectElement>>;
+export { NativeSelect, type NativeSelectProps };

package/dist/_dts/ui/src/popover.d.ts

@@ -6,4 +6,10 @@ declare const PopoverAnchor: React.ForwardRefExoticComponent<PopoverPrimitive.Po
 declare const PopoverContent: React.ForwardRefExoticComponent<Omit<PopoverPrimitive.PopoverContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & {
     container?: HTMLElement | null;
 } & React.RefAttributes<HTMLDivElement>>;
-export { Popover, PopoverTrigger, PopoverContent, PopoverAnchor };
+/**
+ * The modal dialog a popover's trigger sits in, if any. A popover opened from
+ * inside a dialog portals into it, or the dialog's scroll lock and modal
+ * boundary treat the list as outside content.
+ */
+declare function findOwningDialog(trigger: Element | null | undefined): HTMLElement | null;
+export { Popover, PopoverTrigger, PopoverContent, PopoverAnchor, findOwningDialog };

package/dist/_dts/ui/src/segmented-control.d.ts

@@ -13,4 +13,8 @@ export type SegmentedControlProps<T extends string = string> = {
     className?: string;
     'aria-label'?: string;
 };
+/**
+ * A pale track with the chosen option raised on it as a pill. The options
+ * share the track's width equally when the caller makes it wider (`w-full`).
+ */
 export declare function SegmentedControl<T extends string = string>({ options, value, onValueChange, size, className, ...aria }: SegmentedControlProps<T>): React.ReactElement;

package/dist/_dts/ui/src/surface.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { type VariantProps } from 'class-variance-authority';
 export declare const surfaceVariants: (props?: ({
-    variant?: "default" | "background" | null | undefined;
+    variant?: "default" | "background" | "inverse" | null | undefined;
     radius?: "none" | "sm" | "md" | "lg" | "xl" | "flushMobile" | null | undefined;
     padding?: "none" | "sm" | "md" | "lg" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;