@jig-ui/react 0.1.0

package/LICENSE

@@ -0,0 +1,52 @@
+MIT License
+
+Copyright (c) 2026 Nate Bridi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+===============================================================================
+THIRD-PARTY NOTICES
+===============================================================================
+
+This software includes icon artwork derived from Phosphor Icons
+(https://phosphoricons.com), redistributed as SVG path data. Phosphor Icons is
+licensed as follows:
+
+MIT License
+
+Copyright (c) 2023 Phosphor Icons
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,193 @@
+# @jig-ui/react
+
+React components for the Jig design system.
+
+Ships as plain ESM plus a stylesheet — no Vanilla Extract, PostCSS, or other
+build tooling is required in the consuming project.
+
+## Install
+
+```sh
+npm install @jig-ui/react
+```
+
+`react` and `react-dom` (>=19) are peer dependencies. React 19 is required
+because components take `ref` as an ordinary prop rather than through
+`forwardRef`.
+
+## Use
+
+Import the stylesheet once, at your app's entry point:
+
+```js
+import '@jig-ui/react/styles.css';
+```
+
+Then use the components anywhere:
+
+```jsx
+import { Button, Stack, Typography } from '@jig-ui/react';
+
+export function Example() {
+  return (
+    <Stack direction={{ xs: 'column', md: 'row' }} spacing="400">
+      <Typography as="h1" with="heading01">Hello</Typography>
+      <Button variant="primary">Click me</Button>
+    </Stack>
+  );
+}
+```
+
+### Fonts
+
+Jig's type tokens name three families but deliberately do not load them, so that
+the package makes no network requests of its own and you stay in control of how
+the fonts are served. You must make them available yourself, or text will fall
+back to `sans-serif` / `monospace` / `serif`:
+
+| Token             | Family           |
+| ----------------- | ---------------- |
+| `type.family.sans`    | Work Sans        |
+| `type.family.mono`    | Source Code Pro  |
+| `type.family.display` | Amarna           |
+
+All three are variable fonts covering weights 400–700, which is the full range
+the weight tokens use. The quickest option is Google Fonts — add to your
+`<head>`:
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link
+  href="https://fonts.googleapis.com/css2?family=Amarna:wght@400..700&family=Source+Code+Pro:wght@400..700&family=Work+Sans:wght@400..700&display=swap"
+  rel="stylesheet"
+/>
+```
+
+To avoid the third-party request, self-host instead — via `@fontsource-variable`
+packages or your own `@font-face` rules — using the exact family names above.
+
+To substitute your own typefaces, override the custom properties rather than
+loading these at all:
+
+```css
+:root {
+  --type-family-sans: 'Inter', sans-serif;
+}
+```
+
+### Reset
+
+An optional reset is available separately. Import it before `styles.css`:
+
+```js
+import '@jig-ui/react/reset.css';
+```
+
+### Tokens
+
+The design tokens are exported as CSS custom property references, for inline
+styles or your own CSS-in-JS:
+
+```jsx
+import { color, spacing } from '@jig-ui/react/tokens';
+
+<div style={{ background: color.surfaces[100], padding: spacing[500] }} />
+```
+
+Theming is done entirely through CSS custom properties, so you can override any
+token in your own stylesheet without touching the package.
+
+## Theming
+
+### Cascade layers
+
+All of Jig's CSS ships inside cascade layers, declared in this order:
+
+```css
+@layer jig.reset, jig.tokens, jig.base, jig.components;
+```
+
+Both `styles.css` and `reset.css` state this order, so importing them in either
+order gives the same cascade.
+
+Because every Jig rule sits in a layer, **any unlayered CSS you write beats all
+of it**, regardless of selector specificity. Overriding a token is therefore
+just:
+
+```css
+:root {
+  --color-text-primary: #111;
+}
+```
+
+You do not need to out-specify Jig's own `:root[data-theme="dark"]` selectors —
+layer order settles it first. If your app uses layers itself, name Jig's in your
+own `@layer` statement to place your rules deliberately:
+
+```css
+@layer jig.reset, jig.tokens, jig.base, jig.components, app;
+```
+
+`jig.base` currently emits nothing. It is declared so that adding base styles
+later does not renumber an order you have already written against.
+
+`jig.reset` is lowest on purpose. A reset exists to beat the *browser's* default
+styles, and those lose to author CSS at any layer — so layering it takes nothing
+away. It also has to sit below `jig.components`, or its `h1`–`h6` rules would
+override the components' own typography.
+
+### Light and dark
+
+By default Jig follows the operating system via `prefers-color-scheme`. To take
+control, set `data-theme` on the root element:
+
+```html
+<html data-theme="dark">
+```
+
+Both directions are supported: `data-theme="light"` forces light even when the
+OS is dark, and vice versa.
+
+Theme selectors are scoped to `:root`, and deliberately so: a Jig theme is a
+property of the document, not of a subtree. Jig is built for full-document
+applications, where exactly one theme is in effect at a time.
+
+That means these are out of scope by design rather than pending:
+
+- a dark section inside a light page,
+- side-by-side light and dark previews on one page,
+- independently themed embedded widgets or microfrontends.
+
+Subtree theming is not a selector change — primitives and semantic aliases
+inherit differently, and the tooltip's top-layer popover escapes its ancestors
+entirely. If you need any of the above, own the theme at the document level and
+render the two states on separate pages.
+
+### Avoiding a flash of the wrong theme
+
+Following the OS needs no JavaScript and is correct before first paint, because
+it is pure CSS.
+
+A **persisted** preference is different. If you read a stored theme and apply
+`data-theme` after hydration, the user sees the OS theme first and yours a moment
+later. Jig deliberately ships no runtime for this — it is your app's data, and a
+library-injected script cannot know where you keep it. Either render the
+attribute server-side:
+
+```html
+<html data-theme="{{ user.theme }}">
+```
+
+or set it from a small blocking script in `<head>`, before the stylesheet:
+
+```html
+<script>
+  const t = localStorage.getItem('theme');
+  if (t) document.documentElement.dataset.theme = t;
+</script>
+```
+
+## License
+
+MIT

package/dist/adorn/adorn.d.ts

@@ -0,0 +1,38 @@
+import { PolymorphicProps } from '../polymorphic';
+/**
+ * The inline elements Adorn is willing to render as. Restricted rather than
+ * open: `as` changes the semantics of the text, and an arbitrary ElementType
+ * would let it render as something that has no business holding a phrase.
+ */
+export type AdornElement = 'span' | 'strong' | 'em' | 'b' | 'i' | 'code' | 'mark' | 'abbr';
+/**
+ * Which semantic colour the text takes. Weight and slant come from `as`.
+ *
+ * `mono` is named for what it does — switch to the monospace family — rather
+ * than for `<code>`, which it does not imply. Styling text as code without
+ * marking it up as code is a legitimate thing to want (a keyboard shortcut, a
+ * column of figures); pair it with `as="code"` when the semantics apply too.
+ */
+export type AdornStyle = 'muted' | 'accent' | 'danger' | 'mono';
+/** Adorn's own props. The element's own attributes are added by PolymorphicProps. */
+export interface AdornOwnProps {
+    with?: AdornStyle;
+}
+export type AdornProps<E extends AdornElement = 'span'> = PolymorphicProps<E, AdornOwnProps>;
+/**
+ * Colours or emphasises a phrase inside a run of text.
+ *
+ * `with` sets the semantic colour; `as` sets the meaning and brings the
+ * matching weight or slant with it, so use `as="strong"` for importance and
+ * `as="em"` for stress rather than reaching for a visual-only prop.
+ *
+ * `with="mono"` switches to the monospace family without implying code — pair
+ * it with `as="code"` when the content really is code.
+ *
+ * @example
+ * <Typography as="p">
+ *   Deleting this is <Adorn as="strong" with="danger">permanent</Adorn>.
+ *   Run <Adorn as="code" with="mono">pnpm build</Adorn> first.
+ * </Typography>
+ */
+export declare function Adorn<E extends AdornElement = 'span'>({ as, with: adornStyle, className, children, ...props }: AdornProps<E>): import("react/jsx-runtime").JSX.Element;

package/dist/adorn/index.d.ts

@@ -0,0 +1,2 @@
+export { Adorn } from './adorn';
+export type { AdornProps, AdornStyle, AdornElement } from './adorn';

package/dist/box/box.d.ts

@@ -0,0 +1,32 @@
+import { SpacingProps } from '../spacing';
+import { LayoutChildProps } from '../layout';
+import { PolymorphicProps } from '../polymorphic';
+/** The elements a Box is willing to render as. See StackElement. */
+export type BoxElement = 'div' | 'span' | 'section' | 'article' | 'aside' | 'nav' | 'header' | 'footer' | 'main' | 'ul' | 'ol' | 'li';
+/**
+ * Box's own props. All three are the shared child-side set — Box adds nothing
+ * of its own, because being a child is the whole of what it does. The
+ * element's own attributes are added by PolymorphicProps.
+ */
+export interface BoxOwnProps extends SpacingProps, LayoutChildProps {
+}
+export type BoxProps<E extends BoxElement = 'div'> = PolymorphicProps<E, BoxOwnProps>;
+/**
+ * A layout child: an element that positions itself inside a Stack or a Grid.
+ *
+ * Reach for it when the thing you are placing is not itself a layout
+ * container — a bare div, a Typography, a form control that needs to claim a
+ * column span. Stack and Grid already accept these props directly, so nesting
+ * one inside another needs no Box.
+ *
+ * `span` applies inside a Grid, `grow` inside a Stack, and `alignSelf` in
+ * either. A prop that does not apply to the parent is ignored rather than an
+ * error, and all three take responsive values.
+ *
+ * @example
+ * <Grid columns={12} spacing="400">
+ *   <Box span={8}><Article /></Box>
+ *   <Box span={4}><Sidebar /></Box>
+ * </Grid>
+ */
+export declare function Box<E extends BoxElement = 'div'>({ as, span, grow, alignSelf, className, children, ...props }: BoxProps<E>): import("react/jsx-runtime").JSX.Element;

package/dist/box/index.d.ts

@@ -0,0 +1,2 @@
+export { Box } from './box';
+export type { BoxProps, BoxElement } from './box';

package/dist/breakpoints.d.ts

@@ -0,0 +1,35 @@
+export declare const breakpoints: {
+    readonly xs: 0;
+    readonly sm: 480;
+    readonly md: 768;
+    readonly lg: 1024;
+    readonly xl: 1280;
+};
+export type Breakpoint = keyof typeof breakpoints;
+export declare const mediaQueries: {
+    readonly sm: "screen and (min-width: 480px)";
+    readonly md: "screen and (min-width: 768px)";
+    readonly lg: "screen and (min-width: 1024px)";
+    readonly xl: "screen and (min-width: 1280px)";
+};
+/**
+ * The Sprinkles conditions every responsive prop in the system is built from.
+ * Shared so spacing and layout cannot drift into two different sets of
+ * breakpoints, and so `Responsive<T>` describes all of them at once.
+ */
+export declare const responsiveConditions: {
+    xs: {};
+    sm: {
+        '@media': "screen and (min-width: 480px)";
+    };
+    md: {
+        '@media': "screen and (min-width: 768px)";
+    };
+    lg: {
+        '@media': "screen and (min-width: 1024px)";
+    };
+    xl: {
+        '@media': "screen and (min-width: 1280px)";
+    };
+};
+export declare const defaultCondition = "xs";

package/dist/button/button.d.ts

@@ -0,0 +1,37 @@
+import { ButtonHTMLAttributes, Ref } from 'react';
+import { IconName } from '../icon';
+export type ButtonVariant = 'primary' | 'secondary' | 'danger' | 'ghost' | 'smoke';
+export type ButtonSize = 'sm' | 'md' | 'lg';
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    /**
+     * An icon from the curated set, sized and spaced by the button rather than
+     * by the caller. Decorative — the label names the button.
+     */
+    icon?: IconName;
+    /** Which side of the label the icon sits on. */
+    iconPosition?: 'start' | 'end';
+    ref?: Ref<HTMLButtonElement>;
+}
+/**
+ * A button.
+ *
+ * `variant` sets how loud it is: `primary` for the main action in a view,
+ * `secondary` beside it, `danger` for destructive actions, `ghost` for utility
+ * actions on another surface, and `smoke` for controls over imagery or video,
+ * where a translucent blurred pane keeps the content behind visible.
+ *
+ * `icon` takes a name from the curated set and is sized and spaced by the
+ * button; it is decorative, so the label is what names the control. For a
+ * button with no visible label, use `IconButton`, which requires one.
+ *
+ * Defaults to `type="button"`. Pass `type="submit"` explicitly to submit a
+ * form. To navigate rather than act, use `Link` with a button variant.
+ *
+ * @example
+ * <Button variant="primary" icon="arrow-right" iconPosition="end" onClick={save}>
+ *   Save changes
+ * </Button>
+ */
+export declare function Button({ variant, size, icon, iconPosition, type, className, children, ...props }: ButtonProps): import("react/jsx-runtime").JSX.Element;

package/dist/button/index.d.ts

@@ -0,0 +1,2 @@
+export { Button } from './button';
+export type { ButtonProps, ButtonVariant, ButtonSize } from './button';

package/dist/codeblock/codeblock.d.ts

@@ -0,0 +1,28 @@
+import { ComponentPropsWithoutRef, Ref } from 'react';
+export interface CodeBlockProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children'> {
+    /** Display a script name, language, etc. at top of block. */
+    label?: string;
+    /** Content to display as a plain string. */
+    children: string;
+    ref?: Ref<HTMLDivElement>;
+}
+/**
+ * A block of source code with a copy button.
+ *
+ * `children` is the code as a plain string — not markup, and not a
+ * `<pre>`/`<code>` pair, which the component renders for you. Indentation is
+ * preserved exactly, so template literals should be trimmed before they are
+ * passed.
+ *
+ * `label` names the snippet in the bar above it: a file path, a language, or
+ * whatever identifies it. The copy button confirms in place for two seconds
+ * and needs a secure context, since it uses the async clipboard API.
+ *
+ * Long lines scroll horizontally rather than wrapping.
+ *
+ * @example
+ * <CodeBlock label="vite.config.ts">
+ *   {`export default defineConfig({\n  plugins: [react()],\n})`}
+ * </CodeBlock>
+ */
+export declare function CodeBlock({ label, className, children, ...props }: CodeBlockProps): import("react/jsx-runtime").JSX.Element;

package/dist/codeblock/index.d.ts

@@ -0,0 +1,2 @@
+export { CodeBlock } from './codeblock';
+export type { CodeBlockProps } from './codeblock';

package/dist/collapsible/collapsible.d.ts

@@ -0,0 +1,116 @@
+import { CSSProperties, HTMLAttributes, ReactNode, Ref } from 'react';
+import { TypeStyles } from '../typography';
+/**
+ * What a handler receives alongside the new open state.
+ *
+ * Declared here rather than re-exported from Base UI: 0001 settled that
+ * consumers import from `@jig-ui/react` and should not need to know Base UI
+ * exists. This is the subset of its change details that is useful to call —
+ * the object passed at runtime carries more, and passing it through unchanged
+ * is what makes the cancellation reach Base UI.
+ *
+ * Deliberately the same shape as `ToggleChangeDetails`. 0013 D5's outcome
+ * notes that a third consumer should collapse these into one shared type
+ * rather than adding a third near-copy.
+ */
+export interface CollapsibleChangeDetails {
+    /** Cancels the change. The panel does not move. */
+    cancel: () => void;
+    /** The native event behind the change. */
+    readonly event: Event;
+    /** Whether something has already cancelled this change. */
+    readonly isCanceled: boolean;
+}
+export interface CollapsibleProps extends Omit<HTMLAttributes<HTMLDivElement>, 'className' | 'style' | 'children'> {
+    /**
+     * The trigger's visible content — the words that name what is inside.
+     *
+     * Called `label` rather than `trigger` on purpose: `Dialog`'s `trigger`
+     * means "an element that opens this", and a Collapsible owns its button
+     * rather than accepting one. Reusing the name for a different idea is how a
+     * system stops being learnable.
+     */
+    label: ReactNode;
+    /** The panel's contents. */
+    children?: ReactNode;
+    /**
+     * A Typography preset for the trigger's label. Defaults to `body01`, so a
+     * trigger with nothing passed matches the body copy around it; a section
+     * disclosure usually wants `heading05`.
+     *
+     * The same presets `Typography` and `Link` name, from one shared map — so
+     * this is the type style, not a size ramp. Decided in 0013 D2.
+     */
+    with?: TypeStyles;
+    /**
+     * The glyph marking the trigger: `plus` while closed, `minus` while open, at
+     * the trailing edge, sized in `em` so it tracks `with`.
+     *
+     * `false` removes it, for a trigger that is already obviously one. There is
+     * no way to substitute a different glyph — the indicator is the component's,
+     * like every other icon Jig places rather than accepts. Decided in 0013 D3,
+     * whose outcome records that this pair cannot animate: two SVG paths cannot
+     * be tweened, so the indicator cuts rather than transitions.
+     */
+    indicator?: boolean;
+    /** Controlled open state. Omit to let the collapsible manage its own. */
+    open?: boolean;
+    defaultOpen?: boolean;
+    /**
+     * Fires before the change is applied. Call `details.cancel()` to veto it —
+     * which is what makes "do not collapse over a dirty form" expressible.
+     *
+     * Base UI's signature, kept rather than narrowed to `(open) => void` the way
+     * Dialog's is. Decided in 0013 D5.
+     */
+    onOpenChange?: (open: boolean, details: CollapsibleChangeDetails) => void;
+    /** Prevents the panel from being opened or closed. */
+    disabled?: boolean;
+    /**
+     * Keeps the closed panel in the DOM behind `hidden="until-found"`, so the
+     * browser's find-in-page can match text inside it and open the panel.
+     *
+     * Off by default, which is Base UI's default and 0013 D4's decision: a
+     * closed panel's children are not rendered at all and cost nothing until it
+     * opens. Turn this on for content a reader would expect to search — an FAQ,
+     * a reference page.
+     *
+     * Overrides `keepMounted`. In a browser that does not know the value, the
+     * element falls back to plain `hidden`, which is `keepMounted`'s behaviour
+     * rather than a broken one.
+     */
+    hiddenUntilFound?: boolean;
+    /**
+     * Keeps the closed panel in the DOM behind a plain `hidden`. Off by default.
+     *
+     * Reach for it when state inside the panel has to survive being collapsed —
+     * a partly filled form — and findability is not wanted.
+     */
+    keepMounted?: boolean;
+    /** Applied to the root, which is the element a caller would size. */
+    className?: string;
+    style?: CSSProperties;
+    ref?: Ref<HTMLDivElement>;
+}
+/**
+ * A button that shows and hides a panel below it.
+ *
+ * `label` names what is inside and `children` are the contents. Manages its
+ * own state by default; pass `open` and `onOpenChange` to drive it from
+ * elsewhere. `onOpenChange` fires before the change is applied, so calling
+ * `details.cancel()` inside it vetoes the toggle.
+ *
+ * `with` sets the trigger's type from the Typography presets — `body01` by
+ * default, `heading05` for a section disclosure.
+ *
+ * A closed panel is not in the DOM at all, so find-in-page cannot reach it.
+ * Pass `hiddenUntilFound` for content a reader would expect to search.
+ *
+ * Spacing around it comes from the parent, like every other component.
+ *
+ * @example
+ * <Collapsible label="Shipping and returns" with="heading05">
+ *   <Typography as="p">Orders ship within two business days.</Typography>
+ * </Collapsible>
+ */
+export declare function Collapsible({ label, children, with: typeStyle, indicator, open, defaultOpen, onOpenChange, disabled, hiddenUntilFound, keepMounted, className, style, ref, ...props }: CollapsibleProps): import("react/jsx-runtime").JSX.Element;

package/dist/collapsible/index.d.ts

@@ -0,0 +1,2 @@
+export { Collapsible } from './collapsible';
+export type { CollapsibleProps, CollapsibleChangeDetails } from './collapsible';

package/dist/combobox/combobox.d.ts

@@ -0,0 +1,119 @@
+import { CSSProperties, ReactNode, Ref } from 'react';
+export type ComboboxSize = 'sm' | 'md' | 'lg';
+/**
+ * One option. `label` is what the user reads and what the internal filter
+ * matches against; `value` is what comes back.
+ */
+export interface ComboboxItem<Value = string> {
+    value: Value;
+    label: string;
+    disabled?: boolean;
+}
+/**
+ * A labelled set of options.
+ *
+ * Groups are a shape inside `items` rather than a separate prop, because that
+ * is the shape Base UI's own `items` already reads — its `Group<Item>` is
+ * `{ [key: string]: unknown; items: readonly Item[] }`, so this is handed over
+ * without a mapping layer. Decided in apps/docs/decisions/0011-combobox.html
+ * (D2), which also records the cost: flat data has to be reshaped by the caller.
+ */
+export interface ComboboxGroup<Value = string> {
+    label: string;
+    items: readonly ComboboxItem<Value>[];
+}
+interface ComboboxOwnProps<Value> {
+    /**
+     * The options, flat or grouped. A grouped entry is `{ label, items }`; the
+     * two shapes can be mixed in one array, and the type discriminates on the
+     * presence of `items`.
+     */
+    items: readonly (ComboboxItem<Value> | ComboboxGroup<Value>)[];
+    /**
+     * The field's label. Rendered as a real `<label>` bound to the control, so
+     * this is how the combobox gets its accessible name — one without it is
+     * announced as unlabelled.
+     */
+    label?: ReactNode;
+    /** Hint text below the control, associated via `aria-describedby`. */
+    description?: ReactNode;
+    /**
+     * An error message from outside the component. Passing it marks the field
+     * invalid and shows the message unconditionally.
+     */
+    error?: ReactNode;
+    /** Shown in the popup when the query matches nothing. */
+    emptyMessage?: ReactNode;
+    /**
+     * A floor for the popup's width, as any CSS length. The popup matches the
+     * field by default, which is too narrow when the options are longer than the
+     * control — set this to let it grow past the field rather than truncate.
+     */
+    popupMinWidth?: string | number;
+    placeholder?: string;
+    size?: ComboboxSize;
+    disabled?: boolean;
+    required?: boolean;
+    /** Identifies the field when a form is submitted. */
+    name?: string;
+    /**
+     * Applied to the field wrapper, not the control — the wrapper is the element
+     * the surrounding layout sees. Same reasoning Input records.
+     */
+    className?: string;
+    /** Applied to the field wrapper, for the same reason as `className`. */
+    style?: CSSProperties;
+    /** The input — the element you would focus or measure. */
+    ref?: Ref<HTMLInputElement>;
+}
+/** Single selection: one value, or `null` for none. */
+export type ComboboxSingleProps<Value> = ComboboxOwnProps<Value> & {
+    multiple?: false;
+    value?: Value | null;
+    defaultValue?: Value | null;
+    onValueChange?: (value: Value | null) => void;
+};
+/**
+ * Multiple selection. Selected options render as `Token`s inside the field —
+ * 0011 D3, which finally consumes the height 0006 derived from `size.control`
+ * so a Token nests inside a field of the same size.
+ */
+export type ComboboxMultipleProps<Value> = ComboboxOwnProps<Value> & {
+    multiple: true;
+    value?: readonly Value[];
+    defaultValue?: readonly Value[];
+    onValueChange?: (value: Value[]) => void;
+};
+export type ComboboxProps<Value = string> = ComboboxSingleProps<Value> | ComboboxMultipleProps<Value>;
+/**
+ * A text field that filters a list of options as you type.
+ *
+ * Options are passed as `items` rather than as children. Each is
+ * `{ value, label }`, where `label` is shown and matched against the query and
+ * `value` is what `onValueChange` reports. To group them, pass
+ * `{ label, items }` entries instead; the two shapes can be mixed in one array.
+ *
+ * `multiple` turns the value into an array and renders each selection as a
+ * removable chip inside the field, which grows as chips wrap.
+ *
+ * `label` is the accessible name and should always be set. `description` and
+ * `error` are wired to the control for you; passing `error` also marks the
+ * field invalid.
+ *
+ * Filtering happens inside the component, so `items` should be the full set of
+ * options rather than a pre-filtered result.
+ *
+ * @example
+ * <Combobox
+ *   label="Reviewers"
+ *   multiple
+ *   items={[
+ *     { label: 'Engineering', items: [{ value: 'ada', label: 'Ada Lovelace' }] },
+ *     { label: 'Design', items: [{ value: 'grace', label: 'Grace Hopper' }] },
+ *   ]}
+ *   value={reviewers}
+ *   onValueChange={setReviewers}
+ * />
+ */
+export declare function Combobox<Value = string>({ items, label, description, error, emptyMessage, popupMinWidth, placeholder, size, disabled, required, name, multiple, value, defaultValue, onValueChange, className, style, ref, }: ComboboxProps<Value>): import("react/jsx-runtime").JSX.Element;
+export {};