@antadesign/anta 0.3.12 → 0.3.14

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.d.ts

@@ -29,9 +29,17 @@ export declare function wrapLabel(kids: React.ReactNode, tag: string): React.Rea
  * `currentTarget` is still live. (Read as `true` for the falsy-event guard so a
  * missing event never spuriously reads as bubbled.)
  */
-export declare function nativeStateChange<D>(e: CustomEvent<D> | {
+/**
+ * The event a cross-renderer `statechange` handler receives: React wraps the native
+ * `CustomEvent` in a synthetic event (`.nativeEvent`); Preact passes it directly. `D`
+ * is the per-component `detail` vocabulary. Pair with `nativeStateChange` to unwrap.
+ * Exported so the stateful wrappers (`Banner`, and future ones) don't each re-declare
+ * this union — the CLAUDE.md "reuse shared wrapper helpers" rule.
+ */
+export type StateChangeEvent<D> = CustomEvent<D> | {
     nativeEvent: CustomEvent<D>;
-}): {
+};
+export declare function nativeStateChange<D>(e: StateChangeEvent<D>): {
     event: CustomEvent<D>;
     detail?: D;
     isOwn: boolean;

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/Banner.d.ts

@@ -0,0 +1,79 @@
+import type { BaseProps } from "../general_types";
+/** Public props for the `<Banner>` message strip. `message` is the leading
+ *  content, `children` sit between it and `actions`, all centered in one row. */
+export interface BannerProps extends BaseProps {
+    /** Leading message — a string (rendered at the banner type scale) or any node.
+     *  Centered in the bar, followed by `children` and then `actions`. */
+    message?: React.ReactNode;
+    /** Trailing controls (buttons, links) rendered as a compact row after the
+     *  message and `children`. */
+    actions?: React.ReactNode;
+    /** Free content placed BETWEEN the message and the actions. */
+    children?: React.ReactNode;
+    /** Semantic tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for
+     *  a one-off custom tone. Named tones re-point the surface, text, and border
+     *  colour (used if you opt into a border); a custom color keeps its hue while
+     *  lightness/chroma are pinned. `'neutral'` (the default) is the same as omitting it.
+     *  @defaultValue 'neutral' */
+    tone?: "neutral" | "brand" | "info" | "success" | "warning" | "critical" | (string & {});
+    /** Rounded corners for a standalone, floating banner (`border-radius: 999px`,
+     *  which clamps to a stadium) instead of the edge-to-edge strip. Still borderless
+     *  by default. Pass a `number` (px) or a CSS length string for a custom radius. */
+    round?: boolean | number | string;
+    /** Whether the trailing ✕ dismiss button is present. `false` removes it — drive
+     *  dismissal yourself (a controlled `dismissed`, or your own control) instead.
+     *  It doesn't make the banner un-dismissible, it just drops the built-in ✕.
+     *  @defaultValue true */
+    closable?: boolean;
+    /** ARIA role for the strip host. `'status'` (a polite live region, so the notice
+     *  reaches assistive tech) by default; pass `'alert'` for an urgent notice that
+     *  should interrupt, or a landmark role.
+     *  @defaultValue 'status' */
+    role?: string;
+    /** Controlled dismissed state. When provided, the consumer owns visibility: the
+     *  banner follows this prop only, and clicking ✕ *requests* dismissal (reject by
+     *  not updating). **Requires `onDismiss`** — controlled mode never self-hides, so
+     *  without a handler to set `dismissed` the ✕ can't close the banner. Leave
+     *  undefined for uncontrolled. */
+    dismissed?: boolean;
+    /** Initial dismissed state for the uncontrolled case (read once on mount). */
+    defaultDismissed?: boolean;
+    /** Fired when the user dismisses the banner (clicks ✕). Uncontrolled, the banner
+     *  hides itself and this just notifies. Controlled, it's how you accept the
+     *  request — set `dismissed` to `true` (or ignore to reject); pair it with
+     *  `dismissed`, or the banner can't be closed. */
+    onDismiss?: () => void;
+}
+/**
+ * `<Banner>` — a full-width, dismissible message strip with a bottom border.
+ *
+ * A close cousin of `<Card>` with a small, centered horizontal payload:
+ * `message` leads, `children` sit in the middle, `actions` trail, and (when
+ * `closable`) a 40px-wide, full-height ✕ fills the right edge without shifting the centered group.
+ *
+ * A pure, stateless pass-through to `<a-banner>`: the element owns dismissal and
+ * visibility, so the wrapper holds no state and grabs no ref — it maps props to
+ * attributes (safe wherever the host DOM is reconciled, incl. off the UI thread).
+ *
+ * Uncontrolled (`defaultDismissed`): the element owns visibility and the ✕
+ * self-dismisses. Controlled (`dismissed` + `onDismiss`): the wrapper emits
+ * `state="open"|"closed"`; the element treats the attribute as the source of
+ * truth and the ✕ only *requests* dismissal. The element uses Anta's shared
+ * open/closed state contract under the hood — the wrapper presents it as the
+ * banner-natural `dismissed` (closed = dismissed). See STATEFUL-COMPONENTS.md.
+ *
+ * Requires `@antadesign/anta/elements` to be imported (client-side only) to
+ * register the underlying custom element.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <Banner tone="info" message="A new release is available." actions={<Button size="small" label="Update" />} />
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [hidden, setHidden] = useState(false)
+ * <Banner message="Saved." dismissed={hidden} onDismiss={() => setHidden(true)} />
+ * ```
+ */
+export declare const Banner: ({ message, actions, tone, round, closable, role, dismissed, defaultDismissed, onDismiss, className, style, children, ...rest }: BannerProps) => any;

package/dist/components/Banner.js

@@ -0,0 +1,69 @@
+import { jsx, jsxs } from "@antadesign/anta/jsx-runtime";
+import { nativeStateChange, toneStyle, roundStyle, roundAttr } from "../anta_helpers";
+import { Button } from "./Button";
+const Banner = ({
+  message,
+  actions,
+  tone,
+  round,
+  closable,
+  role = "status",
+  dismissed,
+  defaultDismissed,
+  onDismiss,
+  className,
+  style,
+  children,
+  ...rest
+}) => {
+  const controlled = dismissed != null;
+  const computedStyle = roundStyle(
+    round,
+    "--banner-round",
+    toneStyle(tone, "--banner-tone-source", style)
+  );
+  const messageNode = message == null ? null : typeof message === "string" || typeof message === "number" ? /* @__PURE__ */ jsx("a-banner-message", { slot: "message", children: message }) : /* @__PURE__ */ jsx("span", { slot: "message", style: { display: "contents" }, children: message });
+  return /* @__PURE__ */ jsxs(
+    "a-banner",
+    {
+      state: controlled ? dismissed ? "closed" : "open" : void 0,
+      "default-state": !controlled ? defaultDismissed ? "closed" : "open" : void 0,
+      tone: tone && tone !== "neutral" ? tone : void 0,
+      round: roundAttr(round),
+      role,
+      onstatechange: onDismiss ? (e) => {
+        const { detail, isOwn } = nativeStateChange(e);
+        if (isOwn && detail?.next === "closed") onDismiss();
+      } : void 0,
+      class: className,
+      style: computedStyle,
+      ...rest,
+      children: [
+        messageNode,
+        children,
+        actions != null && /* @__PURE__ */ jsx("span", { slot: "actions", style: { display: "contents" }, children: actions }),
+        closable !== false && // A real <a-button> (light DOM → fully styled, keyboard-focusable) in the
+        // element's `close` slot. It fires the bubbling `dismissrequest` event via
+        // a-button's global listener, so dismissing works even without framework
+        // hydration; the element turns that into a dismiss request.
+        // CONTRACT: `data-custom-event` below MUST match `DISMISS_TRIGGER` in the
+        // element (src/elements/a-banner.ts). Duplicated, not shared — importing
+        // the element module here would self-register it and break the
+        // wrapper/element decoupling. Rename in both places.
+        /* @__PURE__ */ jsx("span", { slot: "close", style: { display: "contents" }, children: /* @__PURE__ */ jsx(
+          Button,
+          {
+            priority: "quaternary",
+            icon: "x",
+            tone,
+            "aria-label": "Dismiss",
+            "data-custom-event": "dismissrequest"
+          }
+        ) })
+      ]
+    }
+  );
+};
+export {
+  Banner
+};

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;