@antadesign/anta 0.3.12 → 0.3.13

package/README.md

@@ -1,16 +1,16 @@
 # @antadesign/anta
 
-<a href="https://antithesis.com" target="_blank" rel="noopener noreferrer">Antithesis</a> design system, **Anta**, has three layers: global CSS tokens, framework-agnostic web components that work with plain HTML, and JSX wrappers for React and Preact.
+<a href="https://antithesis.com" target="_blank" rel="noopener noreferrer">Antithesis</a> design system, **Anta**, has three layers: global CSS tokens with swappable themes, framework-agnostic web components that work in plain HTML, and JSX wrappers for React and Preact.
 
-The Antithesis SaaS has an unusual architecture: most of its UI code runs inside a Worker thread, driven by a custom reactive engine that powers Antithesis notebooks. To keep state in sync between the Worker and the UI thread, Anta's web components must be **fully declarative** — they never mutate their own attributes (any internal state changes happen inside Shadow DOM, invisible to the outer document). A self-mutating attribute would break the Worker↔UI sync.
-
-This constraint shapes the architecture: the web components carry the core styling and the occasional browser-API call (e.g. `getBoundingClientRect()`) without imposing a framework. Majority of web components are stateless. The React/Preact wrappers exist for dynamic state and conditional rendering.
+One constraint shapes the architecture. Antithesis runs most of its UI in a Worker thread, driven by a custom reactive engine, and a component that mutates its own attributes would desync the Worker from the UI thread. So Anta's web components are **fully declarative**: they never touch their own attributes, and internal state lives in Shadow DOM, invisible to the outer document. The components carry the styling without imposing a framework, and most are stateless; the JSX wrappers exist for dynamic state and conditional rendering.
 
 ## Installation
 
-`@antadesign/anta` is an NPM package, so you can `npm install @antadesign/anta` or do that with `pnpm` / `bun`.
+```sh
+npm install @antadesign/anta   # or pnpm / bun
+```
 
-Use the latest version from npm, but **always pin an exact version** — `"@antadesign/anta": "0.2.0"` in your `package.json` — rather than a floating tag like `"latest"` or `"dev"`, which can change between installs.
+Pin an exact version in your `package.json` (`"@antadesign/anta": "0.3.12"`) rather than a floating tag like `"latest"`, which can change between installs.
 
 ### Usage
 
@@ -25,24 +25,23 @@ import { Progress } from '@antadesign/anta'
 
 ### What you import (and why)
 
-Anta exposes four independent imports. Tokens + elements + the JSX layer are the minimum to render a styled component; the reset is recommended but skippable.
+Five imports, listed in the order you'd add them. Tokens + elements + the JSX layer render a styled component; the reset is recommended; the theme is opt-in.
 
 | Import | Provides | Skip if… |
 |---|---|---|
-| `@antadesign/anta/tokens.css` | The CSS custom properties — `--bg-1…5`, `--text-1…5`, `--border-1…5`, the `.dark`-ancestor toggling, the base `font-size: 15px`. Also declares the `@layer base, anta, components, utilities;` cascade order. | You're applying your own design tokens at the same variable names. |
-| `@antadesign/anta/reset.css` | Modern small reset (box-sizing, margin reset, replaced-element block, form-control font inheritance, text-wrap defaults) plus Anta's typography opinions for `h1-h6`, `strong`, `ul / ol / menu`, `a` / link states. Lives in `@layer anta`. | You already have a reset and don't want Anta's typography defaults. |
-| `@antadesign/anta/elements` | Side-effect import that registers `<a-progress>`, `<a-text>`, `<a-icon>` as custom elements *and* attaches their per-element CSS (also in `@layer anta`). | You're rendering Anta only on the server (no DOM) and never hydrating. |
-| `@antadesign/anta` | The JSX wrappers (`Progress`, `Text`, `Icon`) — typed React/Preact components that emit `<a-*>` tags. | You're writing the `<a-*>` elements by hand and don't need a JSX layer. |
+| `@antadesign/anta/tokens.css` | The CSS custom properties: six tone seeds (`--anta-seed-neutral`, `--anta-seed-brand`, …), the role scales derived from them (`--bg-1…5`, `--text-1…5`, `--border-1…5`), the `.dark` ancestor toggle, and the base `font-size: 15px`. Also declares the `@layer base, anta, components, utilities` order. Override a seed to reskin its whole tone. | You're supplying your own values for the same variables. |
+| `@antadesign/anta/reset.css` | Small modern reset (box-sizing, margins, form-control font inheritance) plus Anta's typography for headings, lists, and links. Lives in `@layer anta`. | You already have a reset and don't want Anta's typography defaults. |
+| `@antadesign/anta/elements` | Side-effect import: registers every `<a-*>` element and attaches its CSS (also `@layer anta`). Per-element entries register just one — see [Registering elements](#registering-elements). | You render only on the server, or you import per-element entries instead. |
+| `@antadesign/anta` | The JSX wrappers (`Progress`, `Text`, `Icon`, …): typed React/Preact components that emit `<a-*>` tags. | You write the `<a-*>` elements by hand. |
+| `@antadesign/anta/theme-anta.css` *(optional)* | Anta's hand-tuned reference palette. The default palette is seed-derived; import this last for the exact hand-tuned values. | The seed-derived default, or your own palette, is what you want. |
 
-The chain matters: the per-element CSS that ships with `/elements` references variables like `var(--text-1)` and `var(--bg-2)`. Those variables are *only defined* by `tokens.css`. Skip the tokens import and the components render with whatever the surrounding cascade provides — usually nothing styled at all.
-
-`@antadesign/anta/elements` registers **all** elements — convenient, but it includes every element's code (and deps). To keep your bundle lean, import only the elements you use from their per-element entry points instead: `import '@antadesign/anta/elements/a-tooltip'` registers just `<a-tooltip>` **and loads just its CSS**. Unused elements — and any dependencies they pull in — then never enter your bundle. See [Registering elements](#registering-elements).
+The order matters at the top: the element CSS reads `var(--text-1)`, `var(--bg-2)`, and friends, and only `tokens.css` defines them. Skip the tokens import and components render unstyled.
 
 ### Cascade layers
 
-Anta's reset and element CSS live in `@layer anta`. `tokens.css` pre-declares an order of `@layer base, anta, components, utilities;`, which keeps Anta's defaults above any preflight resets (Tailwind's `@layer base`, Normalize, etc.) while letting your own `@layer components` rules and utility-class frameworks like Tailwind (`@layer utilities`) override Anta when you ask them to.
+Anta's reset and element CSS live in `@layer anta`. `tokens.css` pre-declares `@layer base, anta, components, utilities;`: Anta's defaults sit above preflight resets (Tailwind's `@layer base`, Normalize) and below your `@layer components` rules and utility frameworks.
 
-If you need a different order, declare it in your *own* CSS file that loads **before** `tokens.css`. The first mention of each layer name fixes its position:
+For a different order, declare it in your own CSS loaded **before** `tokens.css` — the first mention of each layer name fixes its position:
 
 ```css
 /* your global.css, loaded before anta */
@@ -51,37 +50,33 @@ If you need a different order, declare it in your *own* CSS file that loads **be
 
 CSS custom properties (the `:root { --… }` declarations in `tokens.css`) stay unlayered so they take effect everywhere unconditionally.
 
-> **Gotcha: unlayered hard resets defeat Anta's element rules.**
->
-> A snippet like this in your global CSS — common copy-paste from older reset guides — silently overrides every element rule Anta ships:
+> **Gotcha: an unlayered hard reset defeats Anta's element rules.**
 >
 > ```css
 > *, *::before, *::after { box-sizing: border-box; }
 > * { margin: 0; }
 > ```
 >
-> Unlayered styles **always** beat layered ones in the cascade, regardless of specificity. So `* { margin: 0 }` outranks Anta's `caption { margin-bottom: 0.25em }`, `p { margin: 0 0 1em }`, `ul / ol` padding, and any other per-element default Anta provides — even though those use stronger selectors.
->
-> If you're importing `@antadesign/anta/reset.css`, Anta already does the same universal `box-sizing` and margin reset, *inside* `@layer anta`. The element-level rules sitting on top are intentionally polite defaults — sensible out of the box, trivially overridable when you want something else (any rule in `@layer components` / `@layer utilities`, or any unlayered rule of your own that targets specific elements, wins automatically). **Delete the duplicate hard reset from your global CSS** so those defaults can apply. If you want to keep your own reset, wrap it in `@layer base { … }` so it sits below `anta` in the declared order and Anta's rules still win element-by-element.
+> Unlayered styles beat layered ones regardless of specificity, so this common copy-paste outranks every per-element default Anta ships (`p` margins, list padding, and the rest). `reset.css` already does the same universal reset inside `@layer anta` — delete the duplicate from your global CSS, or wrap your own reset in `@layer base { … }` so Anta's element rules still win.
 
 ## Registering elements
 
-The JSX wrappers (React components) as `Progress` render custom DOM elements as `<a-progress>`. The custom elements themselves must be registered with the browser **before** they appear in the DOM, and registration only works where `HTMLElement` exists — i.e. the UI thread of a real browser. **Node.js (SSR) and Worker threads don't have `HTMLElement`**, so the import is harmless in those environments: it does nothing — registration is skipped silently and the class uses a stand-in base instead of crashing — though it might extend your worker's bundle size a bit.
+The JSX wrappers render `<a-*>` tags, and the classes behind those tags must be registered **before** they appear in the DOM. Registration needs `HTMLElement`, which exists only in the UI thread of a real browser; in Node.js (SSR) and Worker threads the import is a silent no-op that costs nothing but bundle size.
 
 ```ts
 import '@antadesign/anta/elements'  // auto-registers all elements
 ```
 
-**Register only what you use.** `/elements` is the all-in-one convenience import. To trim your bundle, import the specific element entry points instead — each registers just that element and loads just its CSS:
+**Register only what you use.** `/elements` registers everything; per-element entry points register one element and load just its CSS, keeping unused elements (and their dependencies) out of your bundle:
 
 ```ts
 import '@antadesign/anta/elements/a-tooltip'  // only <a-tooltip> + its CSS
 import '@antadesign/anta/elements/a-button'   // only <a-button> + its CSS
 ```
 
-Both styles are side-effect imports (the act of importing registers the element), and both are idempotent and SSR-safe. The granular form keeps unused elements — and any dependencies they pull in — out of your bundle.
+Both forms are side-effect imports, idempotent, and SSR-safe.
 
-The cleanest pattern is a **static, synchronous import at your app's entry file** — outside any component, outside any hook:
+The cleanest pattern is a static import at your app's entry file, outside any component or hook:
 
 ```ts
 // src/main.tsx (or wherever your root render lives)
@@ -91,19 +86,18 @@ import App from './App'
 createRoot(document.getElementById('root')!).render(<App />)
 ```
 
-Bundlers resolve this at module-init time, so by the time any component renders an `<a-progress>`, the custom element class is already registered — there's no flash of un-upgraded elements.
+Bundlers resolve this at module-init time, so the element classes are registered before anything renders: no flash of un-upgraded elements.
 
 > **Why not `useEffect(() => import('@antadesign/anta/elements'), [])`?**
->
-> `useEffect` fires after paint, and the dynamic `import()` itself is asynchronous. In practice the browser paints unregistered custom elements (which collapse to nothing) for a few hundred milliseconds before the upgrade catches up. `useLayoutEffect` doesn't help either: the async import still resolves after paint, and `useLayoutEffect` warns during SSR hydration. A static import at the entry file avoids all of this.
+> `useEffect` fires after paint and the dynamic import resolves later still, so the browser paints unregistered elements (which collapse to nothing) until the upgrade catches up. `useLayoutEffect` doesn't help: the import is still async, and it warns during SSR hydration.
 
-Where to put the static import depends on the runtime:
+Where the static import goes depends on the runtime:
 
-**Plain HTML / static sites** — put it in a `<script type="module">` tag in the document head. That's client-side by default.
+**Plain HTML / static sites** — a `<script type="module">` tag in the document head.
 
-**SSR frameworks (Astro, Next.js)** — register from a script that the framework only ships to the client. In Astro: `<script>import '@antadesign/anta/elements'</script>` (Astro `<script>` tags are client-side by default). In Next.js: a top-level `import` in a Client Component file (the one with `'use client'` at the top) — that file is only bundled into the client chunk, so the import never reaches Node.
+**SSR frameworks (Astro, Next.js)** — a script the framework ships only to the client. In Astro: `<script>import '@antadesign/anta/elements'</script>` (Astro `<script>` tags are client-side by default). In Next.js: a top-level import in a `'use client'` file, which only enters the client chunk.
 
-**React / Preact apps where the UI runs in a Worker thread (the Antithesis setup)** — register the elements in your UI-thread bootstrap code, the script that owns the real DOM. The Worker won't have `HTMLElement`, so the import must not run there.
+**UI in a Worker thread (the Antithesis setup)** — the UI-thread bootstrap, the script that owns the real DOM. The Worker has no `HTMLElement`, so the import must not run there.
 
 ## Framework setup
 
@@ -137,7 +131,7 @@ If you only use the JSX wrappers (`<Button>`, `<Progress>`, …) you need no set
 
 Every `a-*` tag type-checks, all standard HTML tags keep working, and importing anything from `@antadesign/stickers` adds the sticker tags automatically.
 
-**Option B** — if you can't change `jsxImportSource` (a shared tsconfig, Emotion's `@emotion/react` source, an older `@types/react` without the `React.JSX` namespace), merge anta's tag map into your JSX namespace yourself. Anta exports it as a standalone interface, `AntaIntrinsicElements` — and `@antadesign/stickers` exports the matching `StickerIntrinsicElements` — so it's a single `extends` in any `.d.ts` covered by your tsconfig:
+**Option B** — if you can't change `jsxImportSource` (a shared tsconfig, Emotion's `@emotion/react` source), merge anta's tag map into your JSX namespace yourself: anta exports it as `AntaIntrinsicElements` (and `@antadesign/stickers` as `StickerIntrinsicElements`), one `extends` in any `.d.ts` your tsconfig covers:
 
 ```ts
 import type { AntaIntrinsicElements } from '@antadesign/anta'
@@ -166,8 +160,9 @@ Either way the tags stay fully typed — unknown `a-*` tags and wrong prop types
 
 ### Raw web components (no JSX)
 
+The elements work in plain HTML; registering them also loads their CSS. The bare specifier needs a bundler or an import map to resolve.
+
 ```html
-<link rel="stylesheet" href="@antadesign/anta/elements/a-progress.css">
 <script type="module">
   import '@antadesign/anta/elements'
 </script>
@@ -187,7 +182,7 @@ Add the `dark` class to any ancestor element:
 
 ## Fonts
 
-Anta is designed with a customized version of <a href="https://typetype.org/fonts/tt-interphases-pro" target="_blank" rel="noopener noreferrer">TT Interphases Pro</a> in mind, but it doesn't ship any font binaries. Components reference families through the `--sans-serif` and `--monospace` CSS variables and fall back to native system stacks when no font is registered. The base size is `font-size: 15px` on `:root` (so `1rem = 15px`), intentionally diverging from the browser default of 16px to match Antithesis's information-dense layouts — both the variables and the base size live in `tokens.css`.
+Anta is designed for a customized <a href="https://typetype.org/fonts/tt-interphases-pro" target="_blank" rel="noopener noreferrer">TT Interphases Pro</a> but ships no font binaries. Components reference families through the `--sans-serif` and `--monospace` variables and fall back to system stacks. The base size is `font-size: 15px` on `:root` (so `1rem = 15px`), a deliberate step down from the browser's 16px for Antithesis's information-dense layouts. Both live in `tokens.css`.
 
 To use the Antithesis fonts, register your own `@font-face` declarations and override the variables:
 

package/dist/anta_helpers.js

@@ -86,6 +86,11 @@ class SelectableChildElement extends HTMLElementBase {
   ariaProp = "ariaChecked";
   internals = this.attachInternals?.();
   connectedCallback() {
+    if (Object.prototype.hasOwnProperty.call(this, "selected")) {
+      const v = this.selected;
+      delete this.selected;
+      this.selected = v;
+    }
     if (this.hasAttribute("selected")) this.applyState(true);
   }
   attributeChangedCallback(name) {

package/dist/components/Button.d.ts

@@ -56,10 +56,23 @@ export type ContentMode = {
 };
 /** Submit axis — anchors (href) don't carry form-submission props; buttons
  *  don't carry anchor props. (Copy is no longer a Button concern — `ButtonCopy`
- *  composes a `<a-copy>` child; see `copy-props.ts`.) */
+ *  composes a `<a-copy>` child; see `copy-props.ts`.)
+ *
+ *  `href` is **optional** so a conditional URL just works: `href={maybeUrl}`
+ *  (`string | undefined`) type-checks, and a falsy href degrades to a plain
+ *  button — a definite string renders `<a role="button">`, an absent / `undefined`
+ *  href renders `<a-button>`, mirroring the `href != null` runtime check. Keeping
+ *  it required forced a two-render (`href ? … : …`) or a conditional spread, and
+ *  made TypeScript blame the wrong prop: with `href: string | undefined` matching
+ *  neither branch, the intersection fell through to `PriorityMode` and reported a
+ *  spurious "`priority` is missing". The anchor props (`href` / `target` / `rel` /
+ *  `download` / `ping`) still can't combine with the button props (`type` /
+ *  `form`). */
 export type SubmitMode = {
-    /** Renders as `<a role="button">` instead of `<a-button>`. */
-    href: string;
+    /** URL to link to. A definite string renders `<a role="button">`; omit it
+     *  (or pass `undefined`) to render `<a-button>`, so `href={maybeUrl}`
+     *  degrades to a plain button when the URL is absent. */
+    href?: string;
     /** Anchor target. */
     target?: string;
     /** Anchor rel. */
@@ -122,4 +135,4 @@ export type ButtonProps = BaseButtonProps & PriorityMode & ContentMode & SubmitM
  * <Button href="/docs" target="_blank" label="Read the docs" />
  * ```
  */
-export declare const Button: ({ priority, tone, underline, icon, iconTrailing, paddingless, label, size, loading, disabled, selected, round, href, type, form, className, style, children, ...rest }: ButtonProps) => any;
+export declare const Button: ({ priority, tone, underline, icon, iconTrailing, paddingless, label, size, loading, disabled, selected, round, href, target, rel, download, ping, type, form, className, style, children, ...rest }: ButtonProps) => any;

package/dist/components/Button.js

@@ -14,6 +14,10 @@ const Button = ({
   selected,
   round,
   href,
+  target,
+  rel,
+  download,
+  ping,
   type,
   form,
   className,
@@ -72,6 +76,10 @@ const Button = ({
       {
         href,
         "data-anta": "",
+        target,
+        rel,
+        download,
+        ping,
         ...sharedAttrs,
         ...rest,
         children: inner

package/dist/components/InputDate.d.ts

@@ -1,5 +1,6 @@
 import type { BaseProps } from '../general_types';
 import type { IconShape } from '../elements/a-icon.shapes';
+import { type MenuProps } from './Menu';
 /** Snapshot passed as the 2nd argument to `onValueChange` — the new ISO value
  *  (`''` when cleared) plus the field name (mirrors `Input` / `Calendar`). */
 export interface InputDateChangeAttrs {
@@ -43,6 +44,13 @@ export interface InputDateProps extends Omit<BaseProps, 'children'> {
     status?: 'neutral' | 'brand' | 'info' | 'success' | 'warning' | 'critical';
     /** Round the field corners — `true` for fully round, or a number / CSS length. */
     round?: boolean | number | string;
+    /** Preferred placement of the calendar menu relative to the field. Same values as
+     *  `Menu`; it auto-flips and clamps when space runs out.
+     *  @defaultValue bottom-start */
+    placement?: MenuProps['placement'];
+    /** Gap in pixels between the field and the calendar menu.
+     *  @defaultValue 4 */
+    offset?: number;
     /** Show a clear button once the field has a value. */
     clearable?: boolean;
     /** Leading icon at the start of the field — the calendar affordance. Pass
@@ -87,4 +95,4 @@ export interface InputDateProps extends Omit<BaseProps, 'children'> {
  * <InputDate label="Starts" time defaultValue="2026-06-15T09:00" onValueChange={(v) => save(v)} />
  * ```
  */
-export declare const InputDate: ({ value, defaultValue, min, max, locale, name, size, disabled, label, hint, placeholder, status, round, clearable, icon, time, hour12, onValueChange, className, style, ...rest }: InputDateProps) => any;
+export declare const InputDate: ({ value, defaultValue, min, max, locale, name, size, disabled, label, hint, placeholder, status, round, placement, offset, clearable, icon, time, hour12, onValueChange, className, style, ...rest }: InputDateProps) => any;

package/dist/components/InputDate.js

@@ -33,6 +33,8 @@ const InputDate = ({
   placeholder,
   status,
   round,
+  placement,
+  offset,
   clearable,
   icon,
   time,
@@ -154,7 +156,8 @@ const InputDate = ({
       Menu,
       {
         open,
-        placement: "bottom-start",
+        placement: placement ?? "bottom-start",
+        offset,
         autoWidth: true,
         className: styles.calendarMenu,
         onStateChange: (_e, { next }) => setOpen(next),

package/dist/components/Menu.d.ts

@@ -1,11 +1,12 @@
 import type { BaseProps } from '../general_types';
 export interface MenuProps extends BaseProps {
-    /** Preferred placement relative to the trigger. The cross-axis suffix
-     *  (`-start` / `-end`) aligns the left / right edges; no suffix (`bottom` /
-     *  `top`) centers the menu on the trigger. The menu auto-flips vertically and
-     *  clamps horizontally when there isn't room.
+    /** Preferred placement relative to the trigger. `bottom` / `top` place the menu
+     *  below / above; `right` / `left` place it beside (like a submenu flyout). The
+     *  cross-axis suffix (`-start` / `-end`) aligns the near / far edges, and no suffix
+     *  centers on the trigger. The menu flips to the opposite side when the preferred
+     *  one lacks room, and clamps to the viewport.
      *  @defaultValue bottom-start */
-    placement?: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end' | 'bottom' | 'top';
+    placement?: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end' | 'bottom' | 'top' | 'right-start' | 'right-end' | 'left-start' | 'left-end' | 'right' | 'left';
     /** Open on right-click (the `contextmenu` event) of the trigger region
      *  instead of a left click, positioned at the pointer. */
     context?: boolean;

package/dist/components/Select.d.ts

@@ -1,15 +1,23 @@
 import type { BaseProps } from '../general_types';
 import type { IconShape } from '../elements/a-icon.shapes';
 import { type MenuProps } from './Menu';
+/** The type an option `value` may take: `string`, `number`, or `boolean`. Selection
+ *  compares values with `===`. Object-shaped values are out of scope; give the option a
+ *  stable primitive `value` and read the object back off `attrs.option` (or, in
+ *  `SelectFaceted`, use a `custom` facet). */
+export type OptionValue = string | number | boolean;
 /** One option in a `<Select>`. Pass a bare string as shorthand for
  *  `{ value: s, label: s }`. Carries an index signature so you can attach
  *  arbitrary fields (a `ranAt` date, a `status`, …) and read them back in
- *  `renderOption`; the built-in filter still matches on `value`/`label`/`hint`. */
-export interface SelectOption {
-    /** The option's value — its identity, what `value` / `defaultValue` name, and what
-     *  `onValueChange` reports. Unique across the whole `options` tree (selection is
+ *  `renderOption`; the built-in filter still matches on `value`/`label`/`hint`.
+ *
+ *  Generic in the value type `V` (defaults to `string`): `Select` infers `V` from your
+ *  `options`, so `{ value: 365 }` round-trips as `number` through `onValueChange`. */
+export interface SelectOption<V extends OptionValue = string> {
+    /** The option's value (`V`) — its identity, what `value` / `defaultValue` name, and
+     *  what `onValueChange` reports. Unique across the whole `options` tree (selection is
      *  value-keyed and global across groups / submenus). */
-    value: string;
+    value: V;
     /** Visible label. Defaults to `value`. */
     label?: string;
     /** Secondary text under the label (the option row's `hint`). */
@@ -32,11 +40,11 @@ export interface SelectOption {
 /** A titled group of options rendered **inline** under a heading (like `MenuGroup`).
  *  Selection stays global — a group only organizes; its heading isn't selectable.
  *  `disabled` cascades to every descendant. Nest groups / submenus freely. */
-export interface SelectGroup {
+export interface SelectGroup<V extends OptionValue = string> {
     /** The section heading (non-interactive). */
     label: string;
     /** The grouped items — options, or further groups / submenus. */
-    options: SelectItem[];
+    options: SelectItem<V>[];
     /** Disable the whole group (cascades to all descendants). */
     disabled?: boolean;
 }
@@ -44,13 +52,13 @@ export interface SelectGroup {
  *  Navigation only — the parent row opens the submenu and is never itself selectable.
  *  While a filter query is active the tree flattens and a submenu collapses into a
  *  group (its `label` becomes the heading). `disabled` cascades to descendants. */
-export interface SelectSubmenu {
+export interface SelectSubmenu<V extends OptionValue = string> {
     /** The parent row's label — and the group heading when filtering flattens it. */
     label: string;
     /** Leading icon on the parent row. */
     icon?: IconShape;
     /** The submenu's items — options, or further groups / submenus. */
-    submenu: SelectItem[];
+    submenu: SelectItem<V>[];
     /** Disable the whole branch (cascades to all descendants). */
     disabled?: boolean;
 }
@@ -58,13 +66,13 @@ export interface SelectSubmenu {
  *  inline `SelectGroup`, or a flyout `SelectSubmenu`. Discriminated by shape — an
  *  `options` array is a group, a `submenu` array is a submenu, else it's an option.
  *  (`options` / `submenu` are therefore reserved keys on an option object.) */
-export type SelectItem = string | SelectOption | SelectGroup | SelectSubmenu;
+export type SelectItem<V extends OptionValue = string> = string | SelectOption<V> | SelectGroup<V> | SelectSubmenu<V>;
 /** Per-row snapshot passed to `renderOption` / `renderIndicator`. Everything here
  *  is known at render time; the combobox "active" cursor is deliberately absent
  *  (it's a live element state the DOM owns, not a render-time value). */
-export interface OptionState {
+export interface OptionState<V extends OptionValue = string> {
     /** The option's value. */
-    value: string;
+    value: V;
     /** Whether this row is currently selected. */
     selected: boolean;
     /** Whether this row is disabled. */
@@ -81,15 +89,15 @@ export interface EmptyState {
 }
 /** Snapshot passed to `renderTrigger` so a custom trigger can reflect the current
  *  selection and open state. */
-export interface TriggerState {
+export interface TriggerState<V extends OptionValue = string> {
     /** Whether the menu is open — use it for `aria-expanded` and a chevron. */
     open: boolean;
-    /** The current selection: a string (single), a string array (`multiple`), or
+    /** The current selection: a single value (single), an array (`multiple`), or
      *  `undefined` when nothing is chosen. */
-    value: string | string[] | undefined;
+    value: V | V[] | undefined;
     /** The resolved option objects for the current selection (empty when none).
      *  `selected.length` is the multi-select count. */
-    selected: SelectOption[];
+    selected: SelectOption<V>[];
     /** Whether the whole select is disabled. */
     disabled: boolean;
     /** The `icon` shape passed to `Select`, if any — hand it to your trigger
@@ -102,12 +110,12 @@ export interface TriggerState {
  *  row, or the `clearable` "Clear" footer) carries `all: true` instead. **Always
  *  narrow on `'all' in attrs` before reading `option`** — the `all` variant fires
  *  for single-select too (via `clearable`), not just multiple. */
-export type SelectChangeAttrs = {
+export type SelectChangeAttrs<V extends OptionValue = string> = {
     /** The option value that changed — the chosen value (single) or the toggled
      *  row (multiple). */
-    value: string;
+    value: V;
     /** The resolved option object for `value`. */
-    option: SelectOption;
+    option: SelectOption<V>;
     /** Multiple only: whether the change turned selection **on** (true) or off. */
     selected?: boolean;
 } | {
@@ -121,17 +129,21 @@ export type SelectChangeAttrs = {
 /** Props shared by both selection modes, intersected into `SelectProps`. Exported
  *  (and kept as an interface intersected — not a union base via `extends`) so its
  *  members read as `Select`'s *own* props in the generated docs, not inherited. */
-export interface SelectCommonProps extends Omit<BaseProps, 'children'> {
+export interface SelectCommonProps<V extends OptionValue = string> extends Omit<BaseProps, 'children'> {
     /** The options to choose from — bare strings, `SelectOption` objects, `SelectGroup`s
      *  (inline titled sections), or `SelectSubmenu`s (flyout branches). Groups and
      *  submenus nest and mix with plain options. Selection stays global (one `value`,
      *  leaf options only); a filter query flattens the tree into grouped results.
      *
+     *  `Select` infers its value type `V` from these options: `{ value: 365 }` makes
+     *  `onValueChange` report `number`. A mix of value types widens `V` to the union.
+     *
      *  Each leaf `value` is the option's identity and must be **unique across the whole
-     *  tree** — selection is value-keyed, so a value repeated in two sections is one
-     *  logical pick (both rows toggle together; the trigger resolves to the last). Dev
-     *  builds `console.warn` on a duplicate. */
-    options: SelectItem[];
+     *  tree** (selection is value-keyed, so a value repeated in two sections is one logical
+     *  pick: both rows toggle together, the trigger resolves to the last). Values that
+     *  stringify alike (`365` and `"365"`) also collide as row keys; dev builds
+     *  `console.warn` on either. */
+    options: SelectItem<V>[];
     /** Preferred placement of the options menu relative to the trigger. The menu
      *  auto-flips vertically and clamps horizontally when needed.
      *  @defaultValue bottom-start */
@@ -183,7 +195,7 @@ export interface SelectCommonProps extends Omit<BaseProps, 'children'> {
      *  type. `true` uses the built-in matcher — a case-insensitive substring of the
      *  option's **value / label / hint**. Pass a **function** `(option, query) =>
      *  boolean` for custom matching (called per option; return `true` to keep it). */
-    filter?: boolean | ((option: SelectOption, query: string) => boolean);
+    filter?: boolean | ((option: SelectOption<V>, query: string) => boolean);
     /** `multiple` only: a "Select all" row at the top that toggles every enabled
      *  option (the currently-visible ones when a `filter` query is active); its box
      *  shows the mixed state when only some are selected. On by default in
@@ -208,13 +220,13 @@ export interface SelectCommonProps extends Omit<BaseProps, 'children'> {
      *  `OptionState` (`value`/`selected`/`disabled`). Filtering still works (it
      *  matches the option's `value`/`label`/`hint`), but match-highlighting is
      *  skipped — your content owns its own display. */
-    renderOption?: (option: SelectOption, state: OptionState) => React.ReactNode;
+    renderOption?: (option: SelectOption<V>, state: OptionState<V>) => React.ReactNode;
     /** Replace each row's selection **mark** with your own node, drawn at the
      *  leading edge. The row stays the control (`role` + `aria-checked` from
      *  `indicator` / `selection`); only the drawn mark changes, so pair it with an
      *  `indicator` (`'check'` / `'radio'`) or `selection="multiple"` for the
      *  semantics. Composes with `renderOption`. */
-    renderIndicator?: (state: OptionState) => React.ReactNode;
+    renderIndicator?: (state: OptionState<V>) => React.ReactNode;
     /** Render your own trigger in place of the default field. Receives a
      *  `TriggerState` (`open` / `value` / `selected` / `disabled` / `icon`) to drive
      *  its look. **Return exactly one focusable element** (an Anta `Button`, say) —
@@ -225,7 +237,7 @@ export interface SelectCommonProps extends Omit<BaseProps, 'children'> {
      *  trigger owns its own styling: the field props (`label`, `hint`, `size`, `status`,
      *  `placeholder`, `round`) and `className` / `style` apply to the *default* trigger
      *  only — put your own on the element you return. */
-    renderTrigger?: (state: TriggerState) => React.ReactNode;
+    renderTrigger?: (state: TriggerState<V>) => React.ReactNode;
     /** Render content in the menu body when the (filtered) option list is empty —
      *  a "no results" message, a loading indicator (gated on your own external
      *  loading state), or a "create from the query" row. Receives an `EmptyState`
@@ -239,37 +251,37 @@ export interface SelectCommonProps extends Omit<BaseProps, 'children'> {
  * `<Select>` props. `selection` discriminates the value shape: single mode
  * (`value: string`) or `multiple` (`value: string[]`).
  */
-export type SelectProps = SelectCommonProps & ({
-    /** Selection mode. `'single'` (the default) keeps `value` a string and
+export type SelectProps<V extends OptionValue = string> = SelectCommonProps<V> & ({
+    /** Selection mode. `'single'` (the default) keeps `value` a single value and
      *  closes the menu on pick. Switch to `'multiple'` for checkboxes + an
      *  array value.
      *  @defaultValue single */
     selection?: 'single';
-    /** Controlled value — the `value` string of the selected option. When
-     *  provided, the consumer owns selection: the field follows this prop and a
-     *  pick only *requests* a change via `onValueChange` (reject by not updating).
-     *  Leave undefined for uncontrolled. */
-    value?: string;
-    /** Initial value (an option's `value` string) for the uncontrolled case — the
+    /** Controlled value — the `value` of the selected option. When provided, the
+     *  consumer owns selection: the field follows this prop and a pick only
+     *  *requests* a change via `onValueChange` (reject by not updating). Leave
+     *  undefined for uncontrolled. */
+    value?: V;
+    /** Initial value (an option's `value`) for the uncontrolled case — the
      *  wrapper then owns it. */
-    defaultValue?: string;
+    defaultValue?: V;
     /** Fires after the selection changes, with the new value and a
      *  `{ value, option }` snapshot. Select has no discrete element state, so
      *  there is no cancelable `onStateChange` (see the Input event-model note). */
-    onValueChange?: (value: string, attrs: SelectChangeAttrs) => void;
+    onValueChange?: (value: V, attrs: SelectChangeAttrs<V>) => void;
 } | {
     /** Multi-select: checkboxes on every row, the menu stays open while
      *  toggling, the field shows an "N selected" count, and `value` is an array. */
     selection: 'multiple';
-    /** Controlled values — the `value` strings of the selected options (see the
+    /** Controlled values — the `value`s of the selected options (see the
      *  single-select `value` note). */
-    value?: string[];
-    /** Initial values (option `value` strings) for the uncontrolled case. */
-    defaultValue?: string[];
+    value?: V[];
+    /** Initial values (option `value`s) for the uncontrolled case. */
+    defaultValue?: V[];
     /** Fires after any toggle, with the new value array and a `{ value, option,
      *  selected }` snapshot of the row that changed (or `{ all: true }` for the
      *  Select-all row). */
-    onValueChange?: (value: string[], attrs: SelectChangeAttrs) => void;
+    onValueChange?: (value: V[], attrs: SelectChangeAttrs<V>) => void;
 });
 /** Rolled-up selection of a group / submenu subtree: `'none'` / `'all'` of the
  *  descendant leaves selected, or `'some'` in between. On `SelectedGroup` /
@@ -277,26 +289,26 @@ export type SelectProps = SelectCommonProps & ({
 export type SelectionState = 'none' | 'some' | 'all';
 /** A leaf option annotated with its current selection — a `SelectOption` plus
  *  `selected`. Returned by {@link optionsWithSelection}. */
-export type SelectedOption = SelectOption & {
+export type SelectedOption<V extends OptionValue = string> = SelectOption<V> & {
     selected: boolean;
 };
 /** A group with its descendants annotated and a rolled-up `selectionState`.
  *  Returned by {@link optionsWithSelection}. */
-export interface SelectedGroup extends Omit<SelectGroup, 'options'> {
-    options: SelectedItem[];
+export interface SelectedGroup<V extends OptionValue = string> extends Omit<SelectGroup<V>, 'options'> {
+    options: SelectedItem<V>[];
     selectionState: SelectionState;
 }
 /** A submenu with its descendants annotated and a rolled-up `selectionState`.
  *  Returned by {@link optionsWithSelection}. */
-export interface SelectedSubmenu extends Omit<SelectSubmenu, 'submenu'> {
-    submenu: SelectedItem[];
+export interface SelectedSubmenu<V extends OptionValue = string> extends Omit<SelectSubmenu<V>, 'submenu'> {
+    submenu: SelectedItem<V>[];
     selectionState: SelectionState;
 }
 /** One node of the tree from {@link optionsWithSelection}: a leaf `SelectedOption`
  *  (with `selected`), or a `SelectedGroup` / `SelectedSubmenu` (annotated children
  *  + rolled-up `selectionState`). Mirrors `SelectItem` minus the bare-string
  *  shorthand — strings are normalized to `SelectedOption`. */
-export type SelectedItem = SelectedOption | SelectedGroup | SelectedSubmenu;
+export type SelectedItem<V extends OptionValue = string> = SelectedOption<V> | SelectedGroup<V> | SelectedSubmenu<V>;
 /**
  * Project a `Select` `options` tree onto a set of selected values: returns a mirror
  * of the tree with every leaf marked `selected` and every group / submenu carrying a
@@ -319,7 +331,7 @@ export type SelectedItem = SelectedOption | SelectedGroup | SelectedSubmenu;
  * //   { value: 'eng-fe', label: 'Frontend', selected: false }, … ] }
  * ```
  */
-export declare function optionsWithSelection(options: SelectItem[], values: string | string[] | undefined): SelectedItem[];
+export declare function optionsWithSelection<V extends OptionValue = string>(options: SelectItem<V>[], values: V | V[] | undefined): SelectedItem<V>[];
 /**
  * `<Select>` — a single- or multi-select dropdown, composed from `<Input>` (a
  * read-only trigger) and `<Menu>` (the options). `selection` sets behaviour:
@@ -345,4 +357,4 @@ export declare function optionsWithSelection(options: SelectItem[], values: stri
  * />
  * ```
  */
-export declare const Select: (props: SelectProps) => any;
+export declare const Select: <V extends OptionValue = string>(props: SelectProps<V>) => any;