@viraui/react 2026.7.0-next.0 → 2026.7.0

package/dist/components/title/title.d.ts

@@ -9,7 +9,7 @@ type TitleAxisPadding = TitleSpace | [TitleSpace | 0, TitleSpace | 0];
  * Includes standard text and heading HTML attributes such as `children`, `id`, `title`, and event handlers,
  * plus Vira-owned heading typography, color, and layout controls.
  *
- * @default Base HTML pass-through props keep upstream defaults.
+ * @defaultValue Base HTML pass-through props keep upstream defaults.
  */
 export type TitleProps = React.ComponentPropsWithoutRef<'span'> & {
     /**
@@ -17,13 +17,13 @@ export type TitleProps = React.ComponentPropsWithoutRef<'span'> & {
      *
      * Pair this with `size` for most headings so DOM semantics and visual preset stay intentionally aligned.
      *
-     * @default The title renders a `span` root.
+     * @defaultValue The title renders a `span` root.
      */
     render?: useRender.RenderProp;
     /**
      * Ref forwarded to the rendered title root element.
      *
-     * @default No ref is attached.
+     * @defaultValue No ref is attached.
      */
     ref?: React.Ref<HTMLElement>;
     /**
@@ -32,44 +32,44 @@ export type TitleProps = React.ComponentPropsWithoutRef<'span'> & {
      * This controls only the visual preset. Semantic heading choice remains owned by `render`,
      * because `Title` keeps a `span` root unless `render` replaces it.
      *
-     * @default '1'
+     * @defaultValue '1'
      */
     size?: 'display' | '1' | '2' | '3' | '4' | '5' | '6';
     /**
      * Overrides the size preset weight (`font-weight` + `wght` axis).
      *
-     * @default No weight override.
+     * @defaultValue No weight override.
      */
     weight?: number;
     /**
      * Applies a literal color escape hatch.
      *
-     * @default No literal color override.
+     * @defaultValue No literal color override.
      */
     color?: string;
     /**
      * Controls line height through foundation leading tokens.
      *
-     * @default 'm'
+     * @defaultValue 'm'
      */
     lineHeight?: 'none' | 'xs' | 's' | 'm' | 'l';
     /**
      * Aligns text using logical alignment values.
      * Omit so `text-align` inherits from the parent.
      *
-     * @default Inherits parent `text-align`.
+     * @defaultValue Inherits parent `text-align`.
      */
     align?: React.CSSProperties['textAlign'];
     /**
      * Constrains the maximum inline size of the rendered text block.
      *
-     * @default No max width constraint.
+     * @defaultValue No max width constraint.
      */
     maxWidth?: string;
     /**
      * Controls white-space preservation and wrapping behavior.
      *
-     * @default 'normal'
+     * @defaultValue 'normal'
      */
     whiteSpace?: React.CSSProperties['whiteSpace'];
     /**
@@ -78,63 +78,63 @@ export type TitleProps = React.ComponentPropsWithoutRef<'span'> & {
      *
      * Overrides size preset letter-spacing when set.
      *
-     * @default No letter-spacing override.
+     * @defaultValue No letter-spacing override.
      */
     tracking?: React.CSSProperties['letterSpacing'];
     /**
      * Applies `text-transform` on the rendered copy. Prefer this prop over CSS
      * `text-transform` on the same Title root.
      *
-     * @default No text-transform override.
+     * @defaultValue No text-transform override.
      */
     transform?: React.CSSProperties['textTransform'];
     /**
      * Enables balanced wrapping for block-like titles.
      *
-     * @default false
+     * @defaultValue false
      */
     balanced?: boolean;
     /**
      * Enables text selection on the rendered copy.
      *
-     * @default true
+     * @defaultValue true
      */
     selection?: boolean;
     /**
      * Sets inline padding using one token for both sides or a `[start, end]` tuple.
      *
-     * @default No inline padding.
+     * @defaultValue No inline padding.
      */
     hPadding?: TitleAxisPadding;
     /**
      * Sets block padding using one token for both sides or a `[start, end]` tuple.
      *
-     * @default No block padding.
+     * @defaultValue No block padding.
      */
     vPadding?: TitleAxisPadding;
     /**
      * Trims text box whitespace at the chosen edge when the browser supports `text-box`.
      * Pass `false` to disable text-box trim.
      *
-     * @default 'both'
+     * @defaultValue 'both'
      */
     trim?: 'start' | 'end' | 'both' | false;
     /**
      * Selects the `text-box` trim basis when `trim` is active.
      *
-     * @default 'cap alphabetic'
+     * @defaultValue 'cap alphabetic'
      */
     trimType?: string;
     /**
      * Overrides font width as a percentage (100 = normal); maps to `font-stretch` and `wdth`.
      *
-     * @default No width override.
+     * @defaultValue No width override.
      */
     fontWidth?: number;
     /**
      * Overrides the optical size (`opsz`) axis on variable fonts; static fonts keep `font-optical-sizing: auto`.
      *
-     * @default No optical size override.
+     * @defaultValue No optical size override.
      */
     opticalSize?: number;
     /**
@@ -142,7 +142,7 @@ export type TitleProps = React.ComponentPropsWithoutRef<'span'> & {
      * Pass `false` to lock at this size’s `--font-scale-display` / `--font-scale-h*` token.
      * Theme `--effect-fluid-typography: initial` still locks all Title globally.
      *
-     * @default true
+     * @defaultValue true
      */
     fluid?: boolean;
 };

package/dist/components/toast/toast-action.d.ts

@@ -3,7 +3,7 @@ import type * as React from 'react';
 /**
  * Public Toast.Action props.
  *
- * @default Base UI pass-through props keep upstream defaults.
+ * @defaultValue Base UI pass-through props keep upstream defaults.
  */
 export type ToastActionProps = ToastActionNamespace.Props;
 export declare const ToastAction: React.FC<ToastActionProps>;

package/dist/components/toast/toast-banner.d.ts

@@ -15,43 +15,43 @@ export type ToastBannerProps = ToastRootNamespace.Props & {
     /**
      * Heading above the description. Falls back to `toast.title` from `toastManager.add`.
      *
-     * @default `toast.title` when set on the toast instance.
+     * @defaultValue `toast.title` when set on the toast instance.
      */
     title?: React.ReactNode;
     /**
      * Supporting copy below the title.
      *
-     * @default No description is rendered.
+     * @defaultValue No description is rendered.
      */
     description?: React.ReactNode;
     /**
      * Whether to render the dismiss control.
      *
-     * @default true
+     * @defaultValue true
      */
     dismissable?: boolean;
     /**
      * Label for the dismiss control.
      *
-     * @default 'Dismiss'
+     * @defaultValue 'Dismiss'
      */
     dismissLabel?: React.ReactNode;
     /**
      * Called when the dismiss control is activated, before Base UI closes the toast.
      *
-     * @default No callback is invoked.
+     * @defaultValue No callback is invoked.
      */
     onDismiss?: () => void;
     /**
      * Optional action buttons. Accepts a single `Toast.Action` or an array of them.
      *
-     * @default No actions are rendered.
+     * @defaultValue No actions are rendered.
      */
     children?: ToastBannerChildren;
     /**
      * Class name forwarded to the toast root.
      *
-     * @default No extra class name.
+     * @defaultValue No extra class name.
      */
     className?: string;
 };

package/dist/components/toast/toast-viewport.d.ts

@@ -4,13 +4,13 @@ export type ToastViewportPosition = 'bottom-right' | 'bottom-left' | 'bottom-cen
 /**
  * Public Toast.Viewport props.
  *
- * @default `position` is `bottom-right`.
+ * @defaultValue `position` is `bottom-right`.
  */
 export type ToastViewportProps = ToastViewportNamespace.Props & {
     /**
      * Controls viewport placement and stacking layout hooks.
      *
-     * @default 'bottom-right'
+     * @defaultValue 'bottom-right'
      */
     position?: ToastViewportPosition;
 };

package/dist/components/toggle-button/toggle-button.d.ts

@@ -15,38 +15,38 @@ type ToggleButtonAccessibleNameProps = {
  * Icon-only two-state control built on Base UI `Toggle` and `IconButton`.
  * Requires an accessible name via `aria-label` or `aria-labelledby`.
  *
- * @default Base UI toggle pass-through props keep upstream defaults.
+ * @defaultValue Base UI toggle pass-through props keep upstream defaults.
  */
 export type ToggleButtonProps = Omit<IconButtonProps, 'icon' | 'render' | 'variant' | 'children' | 'aria-label' | 'aria-labelledby'> & Omit<TogglePrimitive.Props, 'render' | 'children' | 'aria-label' | 'aria-labelledby'> & ToggleButtonAccessibleNameProps & {
     /**
      * Icon shown while the toggle is not pressed.
      *
-     * @default No default; required for every ToggleButton.
+     * @defaultValue No default; required for every ToggleButton.
      */
     restingIcon: ReactNode;
     /**
      * Icon shown while the toggle is pressed.
      *
-     * @default When omitted, `restingIcon` is shown in both states.
+     * @defaultValue When omitted, `restingIcon` is shown in both states.
      */
     pressedIcon?: ReactNode;
     /**
      * Visual variant while the toggle is not pressed.
      *
-     * @default 'flat'
+     * @defaultValue 'flat'
      */
     variant?: ButtonProps['variant'];
     /**
      * Visual variant while the toggle is pressed.
      *
-     * @default When omitted, `variant` is used in both states.
+     * @defaultValue When omitted, `variant` is used in both states.
      */
     pressedVariant?: ButtonProps['variant'];
     /**
      * When `pressedIcon` is set, crossfade and rotate between resting and pressed icons
      * (`data-interpolate="true"`). When `false`, swap instantly with no transition.
      *
-     * @default false
+     * @defaultValue false
      */
     interpolateIcons?: boolean;
 };

package/dist/components/toggle-group/toggle-group.d.ts

@@ -6,7 +6,7 @@ import { ToggleGroup as ToggleGroupPrimitive } from '@base-ui/react/toggle-group
  * (`row` / `column` from `orientation`) and zero gap — consumers own spacing.
  * Compose `ToggleButton` children each with `value` and an accessible name.
  *
- * @default Base UI pass-through props keep upstream defaults.
+ * @defaultValue Base UI pass-through props keep upstream defaults.
  */
 export type ToggleGroupProps = ToggleGroupPrimitive.Props;
 export declare const ToggleGroup: React.FC<ToggleGroupProps>;

package/dist/components/tooltip/tooltip-content.d.ts

@@ -8,7 +8,7 @@ type TooltipContentPositionerProps = Omit<TooltipPositioner.Props, 'className' |
  * to the Positioner; `sideOffset` defaults to `8`. Always renders the internal
  * Viewport so multi-trigger content animations work by default.
  *
- * @default `sideOffset` is `8`.
+ * @defaultValue `sideOffset` is `8`.
  */
 export type TooltipContentProps = TooltipContentPositionerProps & {
     /**
@@ -16,7 +16,7 @@ export type TooltipContentProps = TooltipContentPositionerProps & {
      * Omit for Base UI default (`document.body` from the module window —
      * iframe hosts must pass the iframe document body explicitly).
      *
-     * @default Base UI FloatingPortal resolution
+     * @defaultValue Base UI FloatingPortal resolution
      */
     container?: React.ComponentProps<typeof PrimitiveTooltip.Portal>['container'];
 };

package/dist/components/typewriter/typewriter.d.ts

@@ -6,55 +6,55 @@ import type * as React from 'react';
  * Includes standard `span` attributes such as `id`, `className`, and event handlers,
  * plus Vira-owned typewriter animation controls.
  *
- * @default Native span pass-through props keep React defaults.
+ * @defaultValue Native span pass-through props keep React defaults.
  */
 export type TypewriterProps = React.ComponentPropsWithRef<'span'> & {
     /**
      * Cycles through multiple phrases instead of a single `children` string.
      *
-     * @default The animation uses string `children` when provided.
+     * @defaultValue The animation uses string `children` when provided.
      */
     texts?: readonly string[];
     /**
      * Selects the caret style rendered after the typed text.
      *
-     * @default 'pipe'
+     * @defaultValue 'pipe'
      */
     caret?: TypewriterCaret;
     /**
      * Overrides the caret color.
      *
-     * @default The caret inherits `currentColor`.
+     * @defaultValue The caret inherits `currentColor`.
      */
     caretColor?: string;
     /**
      * Sets the delay between typed characters in milliseconds.
      *
-     * @default 40
+     * @defaultValue 40
      */
     speed?: number;
     /**
      * Sets the delay between deleted characters in milliseconds.
      *
-     * @default 25
+     * @defaultValue 25
      */
     deleteSpeed?: number;
     /**
      * Sets the pause after a phrase completes before deletion starts, in milliseconds.
      *
-     * @default 2000
+     * @defaultValue 2000
      */
     pause?: number;
     /**
      * Sets the initial delay before typing starts, in milliseconds.
      *
-     * @default 0
+     * @defaultValue 0
      */
     delay?: number;
     /**
      * Repeats the phrase cycle after the final phrase is deleted.
      *
-     * @default true
+     * @defaultValue true
      */
     loop?: boolean;
     /**
@@ -62,7 +62,7 @@ export type TypewriterProps = React.ComponentPropsWithRef<'span'> & {
      * constraints) from first paint through delay, typing, and deletion via an
      * in-flow `visibility: hidden` phrase layer; the typed effect paints absolute on top.
      *
-     * @default false
+     * @defaultValue false
      */
     preserveSpace?: boolean;
 };

package/dist/index.js

@@ -24,6 +24,7 @@ import { DialogIndentBackground } from "./components/dialog/dialog-indent-backgr
 import { DialogSheet } from "./components/dialog/dialog-sheet.js";
 import { DialogTrigger } from "./components/dialog/dialog-trigger.js";
 import { Dialog } from "./components/dialog/dialog.js";
+import { Disclosure } from "./components/disclosure/disclosure.js";
 import { ELEVATION_DEFAULTS } from "./core/elevation/elevation-types.js";
 import { getElevationProps } from "./core/elevation/get-elevation-props.js";
 import { Elevator } from "./components/elevator/elevator.js";
@@ -46,6 +47,7 @@ import { MenuSeparator } from "./components/menu/menu-separator.js";
 import { MenuSubmenuTrigger } from "./components/menu/menu-submenu-trigger.js";
 import { Menu, MenuSubmenu, MenuTrigger } from "./components/menu/menu.js";
 import { Meter } from "./components/meter/meter.js";
+import { NumberField } from "./components/number-field/number-field.js";
 import { Textfield } from "./components/textfield/textfield.js";
 import { OTPField } from "./components/otp-field/otp-field.js";
 import { PopoverSheet } from "./components/popover/popover-sheet.js";
@@ -70,4 +72,4 @@ import { ToggleGroup } from "./components/toggle-group/toggle-group.js";
 import { Typewriter } from "./components/typewriter/typewriter.js";
 import { TooltipContent } from "./components/tooltip/tooltip-content.js";
 import { Tooltip, TooltipProvider, TooltipTrigger } from "./components/tooltip/tooltip.js";
-export { Accordion, Annotate, Autocomplete, Avatar, AvatarGroup, Badge, Beam, Bleed, BreakpointsProvider, Button, ButtonLink, Checkbox, CheckboxGroup, Chip, ClampText, Dialog, DialogClose, DialogIndent, DialogIndentBackground, DialogSheet, DialogTrigger, ELEVATION_DEFAULTS, Elevator, Fieldset, FitText, Glow, Grid, IconButton, IconButtonLink, LinearProgress, Masonry, Menu, MenuCheckboxItem, MenuGroup, MenuItem, MenuLinkItem, MenuPopup, MenuRadioGroup, MenuRadioItem, MenuSeparator, MenuSubmenu, MenuSubmenuTrigger, MenuTrigger, Meter, OTPField, Popover, PopoverClose, PopoverDescription, PopoverSheet, PopoverTitle, PopoverTrigger, ProgressiveBlur, Prose, Radio, RadioGroup, Select, Separator, Shimmer, Skeleton, Slider, Spinner, Stack, StaticNoise, Surface, Switch, Tabs, Text, Textarea, Textfield, Title, Toast, ToggleButton, ToggleGroup, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, Typewriter, getElevationProps, useBreakpoints };
+export { Accordion, Annotate, Autocomplete, Avatar, AvatarGroup, Badge, Beam, Bleed, BreakpointsProvider, Button, ButtonLink, Checkbox, CheckboxGroup, Chip, ClampText, Dialog, DialogClose, DialogIndent, DialogIndentBackground, DialogSheet, DialogTrigger, Disclosure, ELEVATION_DEFAULTS, Elevator, Fieldset, FitText, Glow, Grid, IconButton, IconButtonLink, LinearProgress, Masonry, Menu, MenuCheckboxItem, MenuGroup, MenuItem, MenuLinkItem, MenuPopup, MenuRadioGroup, MenuRadioItem, MenuSeparator, MenuSubmenu, MenuSubmenuTrigger, MenuTrigger, Meter, NumberField, OTPField, Popover, PopoverClose, PopoverDescription, PopoverSheet, PopoverTitle, PopoverTrigger, ProgressiveBlur, Prose, Radio, RadioGroup, Select, Separator, Shimmer, Skeleton, Slider, Spinner, Stack, StaticNoise, Surface, Switch, Tabs, Text, Textarea, Textfield, Title, Toast, ToggleButton, ToggleGroup, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, Typewriter, getElevationProps, useBreakpoints };

package/dist/specs/components/accordion/usage.xml

@@ -8,5 +8,6 @@
   <do>Multiple open sections with root `multiple` (+ `defaultValue` / `value` as needed)</do>
   <dont>Trying to compose separate public `Accordion.Header`, `Accordion.Trigger`, or `Accordion.Panel` exports — those stay inside `Accordion.Item`</dont>
   <dont>Rendering an item without trigger text and without an external aria-label strategy</dont>
+  <dont>Using Accordion for a single expandable section — use Disclosure</dont>
   <dont>Using Accordion for primary navigation that should be links, Tabs, or routes</dont>
 </usage>

package/dist/specs/components/disclosure/a11y.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="disclosure">
+  <rule>Trigger is the disclosing control; Base UI wires expanded/controls relationship to the Panel</rule>
+  <rule>Accessible name comes from Trigger children, or explicit aria-label / aria-labelledby when icon-only</rule>
+  <rule>Trigger icons are decorative (aria-hidden); open/closed is communicated via Base UI attributes/ARIA, not icon alone</rule>
+  <rule>Disabled root ignores pointer and keyboard activation</rule>
+  <rule>prefers-reduced-motion disables Panel height and icon interpolate transitions; open/close still works</rule>
+  <rule>Do not re-apply widget role/aria that Base UI Collapsible already emits</rule>
+</a11y>

package/dist/specs/components/disclosure/meta.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="disclosure" title="Disclosure" category="layout" shared_contract="disclosure">
+  <summary>Single-section expand/collapse wrapping Base UI Collapsible. Default Trigger is Surface with render → Collapsible Trigger; Panel is a height motion shell with no default content padding. Use Accordion for multi-item lists.</summary>
+  <exports>
+    <export name="Disclosure" />
+  </exports>
+  <related>
+    <ref id="accordion" />
+    <ref id="surface" />
+    <ref id="toggle-button" />
+    <ref id="stack" />
+  </related>
+  <units>
+    <unit kind="a11y" href="a11y.xml" />
+    <unit kind="props" href="props.xml" />
+    <unit kind="usage" href="usage.xml" />
+    <unit kind="patterns" href="patterns.xml" />
+  </units>
+  <base_ui href="https://base-ui.com/react/components/collapsible#api-reference" />
+</meta>

package/dist/specs/components/disclosure/patterns.xml

@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="disclosure">
+  <example title="Default Surface Trigger + Panel">
+    <tsx><![CDATA[
+<Disclosure>
+  <Disclosure.Trigger hPadding="m" radius="m" vPadding="m">
+    Shipping details
+  </Disclosure.Trigger>
+  <Disclosure.Panel>
+    <Stack hPadding="m" vPadding="m">
+      <Text tone="muted">Orders ship within 2 business days.</Text>
+    </Stack>
+  </Disclosure.Panel>
+</Disclosure>
+]]></tsx>
+    <notes>Default Trigger = Surface with render → Collapsible.Trigger; hoverColor defaults to 2. Panel is motion-only — pad children in the story/app.</notes>
+  </example>
+
+  <example title="Custom icons with interpolate">
+    <tsx><![CDATA[
+<Disclosure>
+  <Disclosure.Trigger
+    hPadding="m"
+    interpolateIcons
+    openIcon={<Xmark size="1rem" />}
+    radius="m"
+    restingIcon={<Plus size="1rem" />}
+    vPadding="m"
+  >
+    Advanced
+  </Disclosure.Trigger>
+  <Disclosure.Panel>
+    <Stack hPadding="m" vPadding="m">
+      {/* advanced controls */}
+    </Stack>
+  </Disclosure.Panel>
+</Disclosure>
+]]></tsx>
+    <notes>ToggleButton-style resting/open icons; interpolate opt-in. For multi-item lists use Accordion instead.</notes>
+  </example>
+
+  <example title="Custom Trigger render">
+    <tsx><![CDATA[
+<Disclosure>
+  <Disclosure.Trigger render={<Button variant="secondary" />}>
+    Show more
+  </Disclosure.Trigger>
+  <Disclosure.Panel>
+    <Text>Extra details</Text>
+  </Disclosure.Panel>
+</Disclosure>
+]]></tsx>
+    <notes>Consumer render replaces the whole Surface + primitive compose; Surface defaults do not apply.</notes>
+  </example>
+</patterns>

package/dist/specs/components/disclosure/props.xml

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="disclosure">
+  <when_to_use>
+    <item>Single-section progressive disclosure (show more, optional details, FAQ item alone)</item>
+    <item>Expand/collapse one block with Surface chrome Trigger and optional icon pair</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Multi-item collapsible lists — use Accordion</item>
+    <item>Expecting default Panel content padding — Panel is a motion shell only</item>
+    <item>Primary navigation that should use links, Tabs, or routes</item>
+  </when_not_to_use>
+  <prop name="Trigger.restingIcon" kind="react">
+    <description>Decorative icon while the panel is closed. Defaults to ChromeChevronEnd when both icon slots are omitted.</description>
+  </prop>
+  <prop name="Trigger.openIcon" kind="react">
+    <description>Decorative icon while the panel is open. Defaults to ChromeChevronDown when both icon slots are omitted. When only restingIcon is set, that icon shows in both states.</description>
+  </prop>
+  <prop name="Trigger.interpolateIcons" kind="react">
+    <description>When dual icons are present, crossfade and light-rotate between them (`data-interpolate=&quot;true&quot;`). When false, swap instantly with no transition.</description>
+  </prop>
+  <prop name="Trigger.iconPosition" kind="react">
+    <description>Logical side of the label where the icon slot sits (`start` | `end`). Default `end`.</description>
+  </prop>
+  <prop name="Trigger.color" kind="react">
+    <description>Surface resting background on the default Trigger host. Omitted on consumer Trigger render.</description>
+  </prop>
+  <prop name="Trigger.hoverColor" kind="react">
+    <description>Surface hover background on the default Trigger host. Defaults to level 2 when omitted. Skipped when consumer supplies Trigger render.</description>
+  </prop>
+  <prop name="Trigger.border" kind="react">
+    <description>Surface contrast border on the default Trigger host.</description>
+  </prop>
+  <prop name="Trigger.borderStyle" kind="react">
+    <description>Surface border style when border is set on the default Trigger host.</description>
+  </prop>
+  <prop name="Trigger.radius" kind="react">
+    <description>Surface corner radius on the default Trigger host.</description>
+  </prop>
+  <prop name="Trigger.hPadding" kind="react">
+    <description>Surface inline padding on the default Trigger host. Defaults to `m` when omitted. Skipped when consumer supplies Trigger render.</description>
+  </prop>
+  <prop name="Trigger.vPadding" kind="react">
+    <description>Surface block padding on the default Trigger host. Defaults to `s` when omitted. Skipped when consumer supplies Trigger render.</description>
+  </prop>
+  <prop name="Trigger.render" kind="react">
+    <description>Replaces the whole default Surface + Collapsible Trigger compose with a custom host.</description>
+  </prop>
+  <prop name="Panel.hiddenUntilFound" kind="react">
+    <description>Allows browser find-in-page to expand the panel; Base UI Collapsible Panel pass-through.</description>
+  </prop>
+  <prop name="Panel.keepMounted" kind="react">
+    <description>Keeps the panel in the DOM while closed; Base UI Collapsible Panel pass-through.</description>
+  </prop>
+</props>

package/dist/specs/components/disclosure/usage.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="disclosure">
+  <do>Compose `Disclosure` + `Disclosure.Trigger` + `Disclosure.Panel` for a single expandable section</do>
+  <do>Spread Surface chrome on Trigger (`color`, `hoverColor`, `border`, `radius`, padding) when using the default host</do>
+  <do>Supply Panel children layout (Stack/padding) yourself — Panel has no default content padding</do>
+  <do>Use `restingIcon` / `openIcon` / `interpolateIcons` for ToggleButton-style icon pairs; omit both for chrome chevron End/Down</do>
+  <do>Pass Trigger `render` when replacing the Surface compose entirely</do>
+  <dont>Using Accordion for a single section — Accordion is multi-item</dont>
+  <dont>Expecting Accordion-like default Panel padding from Disclosure.Panel</dont>
+  <dont>Relying on icon animation alone for open/closed meaning under reduced motion</dont>
+</usage>

package/dist/specs/components/number-field/a11y.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="number-field">
+  <rule>Visible `label` on `NumberField` names the numeric input via Field.Label / htmlFor.</rule>
+  <rule>Description uses Field description / `aria-describedby` while valid.</rule>
+  <rule>Error copy shares the helper slot and replaces description while invalid and dirty (same as Textfield).</rule>
+  <rule>Internal steppers are icon-only IconButtons named `Decrement` and `Increment`.</rule>
+  <rule>Label scrub is optional chrome (`labelScrub`, default true when label present). Disable with `labelScrub={false}` or omit label.</rule>
+  <rule>Focus order follows `stepperPlacement`: split → decrement, input, increment; grouped → input then both. Grouped visual side follows document direction (inline-end).</rule>
+  <rule>When `description` is a string, NumberField sets `aria-roledescription` on the numeric input to that string; otherwise Base UI default remains.</rule>
+</a11y>

package/dist/specs/components/number-field/meta.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="number-field" title="NumberField" category="form" shared_contract="number-field">
+  <summary>Single public NumberField with Field chrome, internal IconButton steppers, and optional label scrub. Group / Decrement / Increment / ScrubArea stay internal.</summary>
+  <exports>
+    <export name="NumberField" />
+  </exports>
+  <related>
+    <ref id="textfield" />
+    <ref id="icon-button" />
+    <ref id="fieldset" />
+    <ref id="text" />
+    <ref id="stack" />
+  </related>
+  <units>
+    <unit kind="a11y" href="a11y.xml" />
+    <unit kind="props" href="props.xml" />
+    <unit kind="usage" href="usage.xml" />
+    <unit kind="patterns" href="patterns.xml" />
+  </units>
+  <base_ui href="https://base-ui.com/react/components/number-field#api-reference" />
+</meta>

package/dist/specs/components/number-field/patterns.xml

@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="number-field">
+  <example title="Labeled amount">
+    <tsx><![CDATA[
+<NumberField
+  defaultValue={100}
+  label="Amount"
+  description="Enter the amount in your local currency."
+/>
+]]></tsx>
+    <notes>Default split steppers. Label scrub on when label is present.</notes>
+  </example>
+
+  <example title="Form name + bounds">
+    <tsx><![CDATA[
+<Form>
+  <NumberField name="quantity" defaultValue={1} min={0} max={99} step={1} label="Quantity" />
+</Form>
+]]></tsx>
+    <notes>`name` / min / max / step / label on NumberField. `Form` is `@base-ui/react/form`.</notes>
+  </example>
+
+  <example title="Stepper placement grouped">
+    <tsx><![CDATA[
+<NumberField defaultValue={5} label="Count" stepperPlacement="grouped" />
+]]></tsx>
+    <notes>Both steppers at inline-end (LTR right / RTL left). Steppers are fixed secondary IconButtons.</notes>
+  </example>
+
+  <example title="Full width input grow">
+    <tsx><![CDATA[
+<NumberField defaultValue={25} label="Amount" fullWidth />
+]]></tsx>
+    <notes>Row fills the column; only the numeric input flex-grows.</notes>
+  </example>
+
+  <example title="Plain label without scrub">
+    <tsx><![CDATA[
+<NumberField defaultValue={10} label="Amount" labelScrub={false} />
+]]></tsx>
+    <notes>Field label without ScrubArea.</notes>
+  </example>
+</patterns>