twico-ui 1.6.0 → 1.8.0

package/dist/index.d.cts

@@ -1,5 +1,141 @@
 import * as React from 'react';
 
+interface TwicoProviderProps {
+  /** CSP nonce stamped on every injected `<style>` (for `style-src 'nonce-…'` without `unsafe-inline`). */
+  nonce?: string;
+  children?: React.ReactNode;
+}
+
+declare function TwicoProvider(props: TwicoProviderProps): React.JSX.Element;
+
+/** A friendly, partial token surface. Each entry maps to a `--<group>-<key>` CSS variable. */
+interface ThemeTokens {
+  /** `--color-*` (e.g. `{ primary: "#5b5bd6" }`). */
+  colors?: Record<string, string>;
+  /** `--space-*`. */
+  space?: Record<string, string>;
+  /** `--radius-*`. */
+  radius?: Record<string, string>;
+  /** `--font-*`. */
+  font?: Record<string, string>;
+  /** `--shadow-*`. */
+  shadow?: Record<string, string>;
+  /** Motion vars (e.g. `{ "ease-out": "…", "duration-base": "…" }`) — keyed by the full var suffix. */
+  motion?: Record<string, string>;
+}
+
+/** A CSS custom-property style object (`{ "--color-primary": "…" }`). */
+type Theme = Record<`--${string}`, string>;
+
+/** Map a partial token object onto a `--*` CSS-variable style object. */
+declare function createTheme(partial: ThemeTokens): Theme;
+
+interface ThemeProviderProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** A `createTheme()` result, or a raw partial token object. */
+  theme?: Theme | ThemeTokens;
+  /** `"inline"` sets the vars inline (SSR-safe); `"stylesheet"` injects a scoped, nonce-aware rule. @default "inline" */
+  mode?: "inline" | "stylesheet";
+}
+
+declare function ThemeProvider(props: ThemeProviderProps): React.JSX.Element;
+
+interface FormProps extends React.FormHTMLAttributes<HTMLFormElement> {
+  /** Submit handler — runs after `preventDefault()` (unless `preventDefault={false}`). */
+  onSubmit?: (e: React.FormEvent<HTMLFormElement>) => void;
+  /** Call `event.preventDefault()` before `onSubmit`. @default true */
+  preventDefault?: boolean;
+  /** Disable every control (via a `<fieldset disabled>`) and set `aria-busy`. @default false */
+  loading?: boolean;
+  /** Disable every control (via a `<fieldset disabled>`). @default false */
+  disabled?: boolean;
+  /** Vertical gap between children as a spacing-scale step (e.g. 4 → var(--space-4)). */
+  gap?: number;
+}
+
+declare const Form: React.ForwardRefExoticComponent<FormProps & React.RefAttributes<HTMLFormElement>>;
+
+interface VisuallyHiddenProps extends React.HTMLAttributes<HTMLElement> {
+  /** Element to render. @default "span" */
+  as?: React.ElementType;
+}
+
+declare const VisuallyHidden: React.ForwardRefExoticComponent<
+  VisuallyHiddenProps & React.RefAttributes<HTMLElement>
+>;
+
+interface PortalProps {
+  children?: React.ReactNode;
+}
+
+declare function Portal(props: PortalProps): React.ReactPortal | React.ReactNode | null;
+
+interface ColorSchemeScriptOptions {
+  /** localStorage key holding the theme (matches useColorScheme). @default "twico-theme" */
+  storageKey?: string;
+  /** How the scheme is applied: the `dark` class, or a `[data-…]` attribute value. @default "class" */
+  attribute?: string;
+  /** Scheme to use when nothing is stored (skips the prefers-color-scheme probe). */
+  defaultScheme?: "light" | "dark";
+}
+
+interface ColorSchemeScriptProps extends ColorSchemeScriptOptions {
+  /** CSP nonce for the inline `<script>`. */
+  nonce?: string;
+}
+
+/** The theme-init IIFE as a string, for consumers who inject the script themselves. */
+declare function getColorSchemeScript(options?: ColorSchemeScriptOptions): string;
+
+/** A `<script>` for the SSR `<head>` that applies the persisted color scheme before first paint. */
+declare function ColorSchemeScript(props: ColorSchemeScriptProps): React.JSX.Element;
+
+type KbdProps = React.HTMLAttributes<HTMLElement>;
+
+declare const Kbd: React.ForwardRefExoticComponent<KbdProps & React.RefAttributes<HTMLElement>>;
+
+type PreProps = React.HTMLAttributes<HTMLPreElement>;
+
+declare const Pre: React.ForwardRefExoticComponent<PreProps & React.RefAttributes<HTMLPreElement>>;
+
+interface AnchorProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  /** Element to render (e.g. a router Link). @default "a" */
+  as?: React.ElementType;
+  /** Open in a new tab with rel="noopener noreferrer" and a ↗ affix. @default false */
+  external?: boolean;
+}
+
+declare const Anchor: React.ForwardRefExoticComponent<AnchorProps & React.RefAttributes<HTMLAnchorElement>>;
+
+interface LabelProps extends React.LabelHTMLAttributes<HTMLLabelElement> {
+  /** Id of the control this labels. */
+  htmlFor?: string;
+  /** Append a danger-colored asterisk. @default false */
+  required?: boolean;
+  /** @default "md" */
+  size?: "sm" | "md" | "lg";
+}
+
+declare const Label: React.ForwardRefExoticComponent<LabelProps & React.RefAttributes<HTMLLabelElement>>;
+
+interface ImageProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "alt"> {
+  /** Image source URL. */
+  src?: string;
+  /** Alternative text (required for accessibility; pass "" for decorative images). */
+  alt: string;
+  /** object-fit value. */
+  fit?: "cover" | "contain" | "fill" | "none" | "scale-down";
+  /** Border radius token (e.g. "md", "lg", "full"). */
+  radius?: string;
+  /** CSS aspect-ratio (e.g. "16/9"). */
+  aspectRatio?: string;
+  /** Source swapped in if the image fails to load. */
+  fallback?: string;
+  /** @default "lazy" */
+  loading?: "lazy" | "eager";
+}
+
+declare const Image: React.ForwardRefExoticComponent<ImageProps & React.RefAttributes<HTMLImageElement>>;
+
 /**
  * Vertically stacked, expandable disclosure panels with smooth height animation.
  *
@@ -57,6 +193,58 @@ type BarTone = Exclude<Tone, "neutral">;
  */
 type PolymorphicAs = React.ElementType;
 
+/**
+ * The `sx` style-prop escape hatch (#53). Top-level CSS properties are applied as inline
+ * style (and win over the component's base style, MUI-style); any nested object — a
+ * selector key (`"&:hover"`, `":focus-visible"`, `"& > .child"`) or an at-rule
+ * (`"@media (min-width: 600px)"`, `"@supports …"`, `"@container …"`) — is compiled to a
+ * scoped stylesheet. Use design tokens for values, e.g. `color: "var(--color-primary)"`.
+ * See docs/sx.md.
+ */
+type Sx = React.CSSProperties & {
+  [selector: string]: React.CSSProperties[keyof React.CSSProperties] | string | number | Sx | undefined;
+};
+
+// ── Polymorphic component type kit ────────────────────────────────────────────
+// Powers the `as`-driven primitives (Box, Stack, Grid, Container, Text, Heading).
+// Passing `as="a"` narrows the accepted props to that element's attributes (href,
+// target, …) and types `ref` as the matching element (HTMLAnchorElement); the
+// component's own style props always merge on top. `as={RouterLink}` accepts that
+// component's props instead. See docs/polymorphic-types.md and docs/prop-conventions.md.
+
+/** The `ref` type for a given `as` element `C` (e.g. `HTMLAnchorElement` for `"a"`). */
+type PolymorphicRef<C extends React.ElementType> = React.ComponentPropsWithRef<C>["ref"];
+
+/** Own props merged over `E`'s props — the component's own props win on a name clash. */
+type Merge<E, Own> = Own & Omit<E, keyof Own>;
+
+/** Own props + `as={C}`, merged with `C`'s intrinsic props (own props win on a name clash). */
+type PolymorphicProps<C extends React.ElementType, Own = {}> =
+  Merge<React.ComponentPropsWithoutRef<C>, Own> & { as?: C };
+
+/** {@link PolymorphicProps} plus a correctly-typed `ref` for the resolved element. */
+type PolymorphicPropsWithRef<C extends React.ElementType, Own = {}> =
+  PolymorphicProps<C, Own> & { ref?: PolymorphicRef<C> };
+
+/**
+ * The callable type of a polymorphic `forwardRef` component whose default element is `D`.
+ *
+ * Two overloads keep prop-checking strict in both directions: when `as` is omitted the
+ * default element `D` is used and its props (plus the own props) are enforced; when
+ * `as={C}` is given, `C`'s props and a matching `ref` are enforced instead. A single
+ * generic signature would let JSX fall back to the `ElementType` constraint and silently
+ * accept anything, so the overloads are deliberate.
+ */
+interface PolymorphicComponent<Own, D extends React.ElementType> {
+  (
+    props: Merge<React.ComponentPropsWithoutRef<D>, Own> & { as?: never; ref?: PolymorphicRef<D> },
+  ): React.ReactElement | null;
+  <C extends React.ElementType>(
+    props: Merge<React.ComponentPropsWithoutRef<C>, Own> & { as: C; ref?: PolymorphicRef<C> },
+  ): React.ReactElement | null;
+  displayName?: string;
+}
+
 /**
  * Inline message banner with semantic tones, optional title, icon, and dismiss.
  */
@@ -300,6 +488,8 @@ interface CardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title">
   interactive?: boolean;
   /** Stretch to fill the parent cell (`height: 100%`) — equal-height cards in a grid/flex row. */
   fullHeight?: boolean;
+  /** Style escape hatch: flat CSS goes inline; nested selectors/at-rules (`"&:hover"`, `"@media …"`) compile to a scoped stylesheet. */
+  sx?: Sx;
   children?: React.ReactNode;
 }
 
@@ -432,6 +622,8 @@ interface ColorPickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "o
   presets?: string[];
   /** Disable all interaction (the popover cannot be opened). @default false */
   disabled?: boolean;
+  /** Show an alpha slider and emit 8-digit `#RRGGBBAA`; the hex input then accepts 3/6/8-digit hex. @default false */
+  alpha?: boolean;
   /** Color intent for the focus/open accent. @default "primary" */
   tone?: Tone;
   onChange?: (hex: string) => void;
@@ -508,6 +700,10 @@ interface ComboboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>
   emptyText?: string;
   /** Name for a hidden form field so the selected value participates in native form submission. */
   name?: string;
+  /** Virtualize the option list — render only the visible slice (plus `overscan`) for long lists. @default false */
+  virtualized?: boolean;
+  /** Extra option rows rendered above/below the viewport when `virtualized`, to smooth fast scrolling. @default 8 */
+  overscan?: number;
   /** Composed with the field's open-on-focus behavior — your handler runs first. */
   onFocus?: React.FocusEventHandler<HTMLInputElement>;
   /** Composed with the field's keyboard navigation (Arrows/Enter/Escape) — your handler runs first; call `event.preventDefault()` to suppress it. */
@@ -683,10 +879,20 @@ interface DatatableProps<T = any> extends Omit<React.HTMLAttributes<HTMLDivEleme
   batchActions?: DatatableBatchAction<T>[];
   /** Row height preset. With `showDensity`, the toolbar density button cycles it locally; changing this prop re-applies it. @default "comfortable" */
   density?: "compact" | "standard" | "comfortable";
-  /** Initial rows per page. 0 disables pagination. @default 10 */
+  /**
+   * Rows per page. 0 disables pagination. Uncontrolled by default (changing the prop
+   * re-applies it and resets to the first page); becomes **controlled** when
+   * `onPageSizeChange` is supplied. @default 10
+   */
   pageSize?: number;
   /** Options shown in the rows-per-page selector. @default [5, 10, 25, 50] */
   pageSizeOptions?: number[];
+  /** Controlled current page (0-based). When set, the table renders this page and reports changes via `onPageChange` instead of managing its own. */
+  page?: number;
+  /** Fires with the next 0-based page on user pagination (and when a page-size/query change resets to page 0). Required to control `page`. */
+  onPageChange?: (page: number) => void;
+  /** Fires with the next rows-per-page when the user picks one; supplying it makes `pageSize` controlled. */
+  onPageSizeChange?: (pageSize: number) => void;
   /** Max height of the scroll area in px (header/footer stay fixed). @default 440 */
   height?: number;
   /**
@@ -949,6 +1155,10 @@ interface DatePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "on
   tone?: Tone;
   /** Show a clear (×) button when a date is set. @default true */
   clearable?: boolean;
+  /** Render the trigger as a typeable text input with a trailing calendar toggle; typed text commits via `parse` on Enter/blur. @default false */
+  editable?: boolean;
+  /** Parse typed text into a Date (used when `editable`). Return a `Date` to commit, `null`/invalid to revert. Defaults to a lenient `Date.parse`. */
+  parse?: (text: string) => Date | null;
   /** Custom display formatter (defaults to a localized medium date). */
   format?: (date: Date) => string;
   /** BCP-47 locale for month/weekday names + date formatting (Intl). Omit for the runtime default. @default undefined */
@@ -1001,6 +1211,10 @@ interface DateRangePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>
   disabled?: boolean;
   /** Color intent for the focus/open accent. @default "primary" */
   tone?: Tone;
+  /** Render the trigger as a typeable input accepting "start – end"; typed text commits via `parse` on Enter/blur. @default false */
+  editable?: boolean;
+  /** Parse one side of the typed range into a Date (used when `editable`). Return a `Date` to accept, `null`/invalid to reject. Defaults to a lenient `Date.parse`. */
+  parse?: (text: string) => Date | null;
   onChange?: (range: DateRange) => void;
 }
 
@@ -1357,6 +1571,10 @@ interface MultiSelectProps extends Omit<React.InputHTMLAttributes<HTMLInputEleme
   max?: number;
   /** Collapse chips after N into a "+K more" pill. */
   maxTagCount?: number;
+  /** Virtualize the option list — render only the visible slice (plus `overscan`) for long lists. @default false */
+  virtualized?: boolean;
+  /** Extra option rows rendered above/below the viewport when `virtualized`, to smooth fast scrolling. @default 8 */
+  overscan?: number;
   /** Composed with the field's open-on-focus behavior — your handler runs first. */
   onFocus?: React.FocusEventHandler<HTMLInputElement>;
   /** Composed with the field's keyboard navigation (Arrows/Enter/Escape/Backspace) — your handler runs first; call `event.preventDefault()` to suppress it. */
@@ -1651,6 +1869,10 @@ interface SelectProps extends Omit<React.HTMLAttributes<HTMLButtonElement>, "onC
   emptyText?: string;
   /** Name for a hidden form field so the selected value participates in native form submission. */
   name?: string;
+  /** Virtualize the option list — render only the visible slice (plus `overscan`) for long lists. @default false */
+  virtualized?: boolean;
+  /** Extra option rows rendered above/below the viewport when `virtualized`, to smooth fast scrolling. @default 8 */
+  overscan?: number;
 }
 
 /** Alias of the shared {@link Option} type (kept for backward-compatible imports). */
@@ -2229,16 +2451,12 @@ interface AppShellProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "chil
 
 declare function AppShell(props: AppShellProps): React.JSX.Element;
 
-/** Generic, token-styled element — the building block for non-flex layout. */
-interface BoxProps extends React.HTMLAttributes<HTMLElement> {
-  /** Element/tag to render. @default "div" */
-  as?: PolymorphicAs;
-  /** Link destination — only used with as="a"; scheme-sanitized (javascript:/data:/vbscript: render without href). */
-  href?: string;
-  /** Anchor target — only used with as="a" (e.g. "_blank"). */
-  target?: React.HTMLAttributeAnchorTarget;
-  /** Anchor rel — only used with as="a"; pair "noopener noreferrer" with target="_blank". */
-  rel?: string;
+/**
+ * Box's own (non-polymorphic) props. The rendered element's intrinsic attributes —
+ * and `ref` — are added by the polymorphic wrapper based on `as` (e.g. `as="a"`
+ * contributes `href`/`target`/`rel` and a `Ref<HTMLAnchorElement>`).
+ */
+interface BoxOwnProps {
   /** Padding (all / x / y / individual) — spacing step (number) or CSS length. */
   p?: number | string;
   px?: number | string;
@@ -2263,41 +2481,47 @@ interface BoxProps extends React.HTMLAttributes<HTMLElement> {
   radius?: string;
   /** Box-shadow token suffix (e.g. "sm", "lg", "xl"). */
   shadow?: string;
+  /** Style escape hatch: flat CSS goes inline (wins over base); nested selectors/at-rules (`"&:hover"`, `"@media …"`) compile to a scoped stylesheet. */
+  sx?: Sx;
 }
 
-declare function Box(props: BoxProps): React.JSX.Element;
+/**
+ * Box props for a given element `C` (defaults to `"div"`) — Box's own props plus
+ * `C`'s intrinsic attributes and a matching `ref`. Name it directly when wrapping
+ * Box in your own typed component.
+ */
+type BoxProps<C extends React.ElementType = "div"> = PolymorphicPropsWithRef<C, BoxOwnProps>;
 
-/** Centered, max-width content wrapper with responsive horizontal padding. */
-interface ContainerProps extends React.HTMLAttributes<HTMLElement> {
-  /** Element/tag to render. @default "div" */
-  as?: PolymorphicAs;
-  /** Link destination — only used with as="a"; scheme-sanitized (javascript:/data:/vbscript: render without href). */
-  href?: string;
-  /** Anchor target — only used with as="a" (e.g. "_blank"). */
-  target?: React.HTMLAttributeAnchorTarget;
-  /** Anchor rel — only used with as="a"; pair "noopener noreferrer" with target="_blank". */
-  rel?: string;
+/** Generic, token-styled element — the building block for non-flex layout. Polymorphic via `as`. */
+declare const Box: PolymorphicComponent<BoxOwnProps, "div">;
+
+/**
+ * Container's own props. Intrinsic attributes of the rendered element (and `ref`)
+ * are added by the polymorphic wrapper based on `as`.
+ */
+interface ContainerOwnProps {
   /** Max width: a named size (sm 640 / md 768 / lg 1024 / xl 1280 / full) or any CSS length. @default "lg" */
   size?: "sm" | "md" | "lg" | "xl" | "full" | string;
   /** Apply horizontal padding. @default true */
   padded?: boolean;
+  /** Style escape hatch: flat CSS goes inline (wins over base); nested selectors/at-rules (`"&:hover"`, `"@media …"`) compile to a scoped stylesheet. */
+  sx?: Sx;
 }
 
-declare function Container(props: ContainerProps): React.JSX.Element;
+/** Container props for a given element `C` (defaults to `"div"`). */
+type ContainerProps<C extends React.ElementType = "div"> = PolymorphicPropsWithRef<C, ContainerOwnProps>;
+
+/** Centered, max-width content wrapper with responsive horizontal padding. Polymorphic via `as`. */
+declare const Container: PolymorphicComponent<ContainerOwnProps, "div">;
 
 /** Responsive column counts per breakpoint (base + sm/md/lg/xl at 640/768/1024/1280px). */
 type ResponsiveColumns = { base?: number; sm?: number; md?: number; lg?: number; xl?: number };
 
-/** CSS grid primitive — fixed columns or a responsive auto-fill grid. */
-interface GridProps extends React.HTMLAttributes<HTMLElement> {
-  /** Element/tag to render. @default "div" */
-  as?: PolymorphicAs;
-  /** Link destination — only used with as="a"; scheme-sanitized (javascript:/data:/vbscript: render without href). */
-  href?: string;
-  /** Anchor target — only used with as="a" (e.g. "_blank"). */
-  target?: React.HTMLAttributeAnchorTarget;
-  /** Anchor rel — only used with as="a"; pair "noopener noreferrer" with target="_blank". */
-  rel?: string;
+/**
+ * Grid's own props. Intrinsic attributes of the rendered element (and `ref`) are
+ * added by the polymorphic wrapper based on `as`.
+ */
+interface GridOwnProps {
   /** Fixed column count, or a responsive object `{ base, sm, md, lg, xl }` (ignored when `minChildWidth` is set). */
   columns?: number | ResponsiveColumns;
   /** Responsive auto-fill: minimum child width (number = px, or any CSS length). */
@@ -2314,20 +2538,21 @@ interface GridProps extends React.HTMLAttributes<HTMLElement> {
   alignContent?: React.CSSProperties["alignContent"];
   /** Distribute the grid's columns within extra inline space. */
   justifyContent?: React.CSSProperties["justifyContent"];
+  /** Style escape hatch: flat CSS goes inline (wins over base); nested selectors/at-rules (`"&:hover"`, `"@media …"`) compile to a scoped stylesheet. */
+  sx?: Sx;
 }
 
-declare function Grid(props: GridProps): React.JSX.Element;
+/** Grid props for a given element `C` (defaults to `"div"`). */
+type GridProps<C extends React.ElementType = "div"> = PolymorphicPropsWithRef<C, GridOwnProps>;
 
-/** Flex layout primitive — rows or columns with token-based gaps. */
-interface StackProps extends React.HTMLAttributes<HTMLElement> {
-  /** Element/tag to render. @default "div" */
-  as?: PolymorphicAs;
-  /** Link destination — only used with as="a"; scheme-sanitized (javascript:/data:/vbscript: render without href). */
-  href?: string;
-  /** Anchor target — only used with as="a" (e.g. "_blank"). */
-  target?: React.HTMLAttributeAnchorTarget;
-  /** Anchor rel — only used with as="a"; pair "noopener noreferrer" with target="_blank". */
-  rel?: string;
+/** CSS grid primitive — fixed columns or a responsive auto-fill grid. Polymorphic via `as`. */
+declare const Grid: PolymorphicComponent<GridOwnProps, "div">;
+
+/**
+ * Stack's own props. Intrinsic attributes of the rendered element (and `ref`) are
+ * added by the polymorphic wrapper based on `as` (e.g. `as="a"` adds `href`).
+ */
+interface StackOwnProps {
   /** @default "column" */
   direction?: "row" | "column" | "row-reverse" | "column-reverse";
   /** Gap as a spacing-scale step (number) or any CSS length. @default 4 */
@@ -2354,9 +2579,15 @@ interface StackProps extends React.HTMLAttributes<HTMLElement> {
   pl?: number | string;
   /** Node rendered between each child (not before the first or after the last). Pass an orientation-appropriate `Divider`. */
   divider?: React.ReactNode;
+  /** Style escape hatch: flat CSS goes inline (wins over base); nested selectors/at-rules (`"&:hover"`, `"@media …"`) compile to a scoped stylesheet. */
+  sx?: Sx;
 }
 
-declare function Stack(props: StackProps): React.JSX.Element;
+/** Stack props for a given element `C` (defaults to `"div"`). */
+type StackProps<C extends React.ElementType = "div"> = PolymorphicPropsWithRef<C, StackOwnProps>;
+
+/** Flex layout primitive — rows or columns with token-based gaps. Polymorphic via `as`. */
+declare const Stack: PolymorphicComponent<StackOwnProps, "div">;
 
 /** Inline code, or a scrollable multi-line block with an optional copy button. */
 interface CodeProps extends React.HTMLAttributes<HTMLElement> {
@@ -2385,18 +2616,12 @@ type HeadingSize =
   | "xs" | "sm" | "base" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "5xl" | "6xl" | "7xl" | "display";
 
 /**
- * Heading (h1–h6) with token typography. `level` sets the tag/semantics; `size` sets the visual
- * scale — the two are intentionally independent (e.g. a semantic `<h1>` at a small size).
+ * Heading's own props. `level` sets the tag/semantics; `size` sets the visual scale —
+ * the two are intentionally independent (e.g. a semantic `<h1>` at a small size). The
+ * rendered element's intrinsic attributes (and `ref`) are added by the polymorphic
+ * wrapper based on `as`, which overrides the tag chosen by `level`.
  */
-interface HeadingProps extends React.HTMLAttributes<HTMLElement> {
-  /** Override the rendered tag (e.g. render a visual h2 as an h1). */
-  as?: PolymorphicAs;
-  /** Link destination — only used with as="a"; scheme-sanitized (javascript:/data:/vbscript: render without href). */
-  href?: string;
-  /** Anchor target — only used with as="a" (e.g. "_blank"). */
-  target?: React.HTMLAttributeAnchorTarget;
-  /** Anchor rel — only used with as="a"; pair "noopener noreferrer" with target="_blank". */
-  rel?: string;
+interface HeadingOwnProps {
   /** Heading level 1–6 — sets the tag and the default size. @default 2 */
   level?: 1 | 2 | 3 | 4 | 5 | 6;
   /** Font-size token (xs…7xl or display), independent of `level`. */
@@ -2408,20 +2633,21 @@ interface HeadingProps extends React.HTMLAttributes<HTMLElement> {
   truncate?: boolean;
   /** Clamp to N lines with an ellipsis (multi-line, -webkit-line-clamp). Overrides `truncate`. */
   lineClamp?: number;
+  /** Style escape hatch: flat CSS goes inline (wins over base); nested selectors/at-rules (`"&:hover"`, `"@media …"`) compile to a scoped stylesheet. */
+  sx?: Sx;
 }
 
-declare function Heading(props: HeadingProps): React.JSX.Element;
+/** Heading props for a given element `C` (defaults to `"h2"`). */
+type HeadingProps<C extends React.ElementType = "h2"> = PolymorphicPropsWithRef<C, HeadingOwnProps>;
 
-/** Body text with token sizes and semantic color tones. Renders <p> by default. */
-interface TextProps extends React.HTMLAttributes<HTMLElement> {
-  /** Element/tag to render (e.g. "span", "p"). @default "p" */
-  as?: PolymorphicAs;
-  /** Link destination — only used with as="a"; scheme-sanitized (javascript:/data:/vbscript: render without href). */
-  href?: string;
-  /** Anchor target — only used with as="a" (e.g. "_blank"). */
-  target?: React.HTMLAttributeAnchorTarget;
-  /** Anchor rel — only used with as="a"; pair "noopener noreferrer" with target="_blank". */
-  rel?: string;
+/** Heading (h1–h6) with token typography. Polymorphic via `as` (overrides the `level` tag). */
+declare const Heading: PolymorphicComponent<HeadingOwnProps, "h2">;
+
+/**
+ * Text's own props. Intrinsic attributes of the rendered element (and `ref`) are
+ * added by the polymorphic wrapper based on `as` (e.g. `as="a"` adds `href`).
+ */
+interface TextOwnProps {
   /** Font-size token suffix. @default "base" */
   size?: "xs" | "sm" | "base" | "lg" | "xl" | string;
   /** Semantic color tone — text roles (default/muted/subtle), the color intents, or `"inherit"` to adopt the parent color. @default "default" */
@@ -2433,9 +2659,15 @@ interface TextProps extends React.HTMLAttributes<HTMLElement> {
   truncate?: boolean;
   /** Clamp to N lines with an ellipsis (multi-line, -webkit-line-clamp). Overrides `truncate`. */
   lineClamp?: number;
+  /** Style escape hatch: flat CSS goes inline (wins over base); nested selectors/at-rules (`"&:hover"`, `"@media …"`) compile to a scoped stylesheet. */
+  sx?: Sx;
 }
 
-declare function Text(props: TextProps): React.JSX.Element;
+/** Text props for a given element `C` (defaults to `"p"`). */
+type TextProps<C extends React.ElementType = "p"> = PolymorphicPropsWithRef<C, TextOwnProps>;
+
+/** Body text with token sizes and semantic color tones. Renders `<p>` by default; polymorphic via `as`. */
+declare const Text: PolymorphicComponent<TextOwnProps, "p">;
 
 /** SSR-safe `useLayoutEffect` (falls back to `useEffect` on the server). */
 declare const useIsomorphicLayoutEffect: typeof React.useLayoutEffect;
@@ -2586,6 +2818,8 @@ declare function useId(prefix?: string): string;
 interface UseFocusTrapOptions {
   /** Restore focus to the previously-focused element when the trap deactivates. @default true */
   restoreFocus?: boolean;
+  /** Element to focus on activate instead of the first focusable — a ref or a `() => Element | null`. */
+  initialFocus?: React.RefObject<HTMLElement | null> | (() => HTMLElement | null | undefined);
 }
 
 /**
@@ -2606,4 +2840,4 @@ declare function useFocusTrap<T extends HTMLElement = HTMLElement>(
  */
 declare function usePortal(): (node: React.ReactNode) => React.ReactPortal | React.ReactNode | null;
 
-export { Accordion, type AccordionItem, type AccordionProps, type ActionTone, Alert, type AlertProps, AppShell, type AppShellProps, Avatar, AvatarMenu, type AvatarMenuProps, type AvatarProps, Badge, type BadgeProps, type BarTone, Box, type BoxProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, type ButtonProps, Card, type CardProps, Carousel, type CarouselProps, Chart, type ChartDatum, type ChartProps, Checkbox, type CheckboxProps, Code, type CodeProps, ColorPicker, type ColorPickerProps, Combobox, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type Command, CommandPalette, type CommandPaletteProps, Container, type ContainerProps, Currency, CurrencyField, type CurrencyFieldProps, type CurrencyOption, type CurrencyProps, Datatable, type DatatableBatchAction, type DatatableColumn, type DatatableFilter, type DatatableFilterOp, type DatatableNumberOp, type DatatableProps, type DatatableQuery, type DatatableRowAction, type DatatableStringOp, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, Dialog, type DialogProps, Divider, type DividerProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, Field, type FieldProps, FileUpload, type FileUploadProps, Grid, type GridProps, Heading, type HeadingProps, type HeadingSize, IconButton, type IconButtonProps, Input, type InputProps, Kanban, type KanbanCard, type KanbanColumn, type KanbanProps, List, type ListItemData, type ListProps, Menu, type MenuItemDef, type MenuProps, MultiSelect, type MultiSelectGroup, type MultiSelectOption, type MultiSelectProps, Navbar, type NavbarLink, type NavbarProps, type Option, type OptionGroup, Pagination, type PaginationProps, type PolymorphicAs, Popover, type PopoverProps, Progress, type ProgressProps, Radio, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioProps, Rating, type RatingProps, type ResponsiveColumns, Select, type SelectGroup, type SelectOption, type SelectProps, Sidebar, type SidebarItem, type SidebarProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Spinner, type SpinnerProps, Stack, type StackProps, Stat, type StatProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextProps, type TextTone, Textarea, type TextareaProps, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastApi, type ToastOptions, type ToastProps, ToastProvider, type ToastProviderProps, type ToastTone, ToastViewport, type ToastViewportProps, type Tone, Tooltip, type TooltipProps, type TreeNode, TreeView, type TreeViewProps, type UseColorSchemeOptions, type UseFocusTrapOptions, type UseKeyPressOptions, type UseMediaQueryOptions, runDatatableQuery, useClickOutside, useColorScheme, useControllableState, useCopyToClipboard, useDebouncedCallback, useDebouncedValue, useDisclosure, useEventListener, useFocusTrap, useHover, useId, useIntersectionObserver, useInterval, useIsomorphicLayoutEffect, useKeyPress, useLocalStorage, useMediaQuery, useMounted, usePortal, usePrefersReducedMotion, usePrevious, useScrollLock, useTimeout, useToast, useToggle, useWindowSize };
+export { Accordion, type AccordionItem, type AccordionProps, type ActionTone, Alert, type AlertProps, Anchor, type AnchorProps, AppShell, type AppShellProps, Avatar, AvatarMenu, type AvatarMenuProps, type AvatarProps, Badge, type BadgeProps, type BarTone, Box, type BoxOwnProps, type BoxProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, type ButtonProps, Card, type CardProps, Carousel, type CarouselProps, Chart, type ChartDatum, type ChartProps, Checkbox, type CheckboxProps, Code, type CodeProps, ColorPicker, type ColorPickerProps, ColorSchemeScript, type ColorSchemeScriptOptions, type ColorSchemeScriptProps, Combobox, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type Command, CommandPalette, type CommandPaletteProps, Container, type ContainerOwnProps, type ContainerProps, Currency, CurrencyField, type CurrencyFieldProps, type CurrencyOption, type CurrencyProps, Datatable, type DatatableBatchAction, type DatatableColumn, type DatatableFilter, type DatatableFilterOp, type DatatableNumberOp, type DatatableProps, type DatatableQuery, type DatatableRowAction, type DatatableStringOp, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, Dialog, type DialogProps, Divider, type DividerProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, Field, type FieldProps, FileUpload, type FileUploadProps, Form, type FormProps, Grid, type GridOwnProps, type GridProps, Heading, type HeadingOwnProps, type HeadingProps, type HeadingSize, IconButton, type IconButtonProps, Image, type ImageProps, Input, type InputProps, Kanban, type KanbanCard, type KanbanColumn, type KanbanProps, Kbd, type KbdProps, Label, type LabelProps, List, type ListItemData, type ListProps, Menu, type MenuItemDef, type MenuProps, MultiSelect, type MultiSelectGroup, type MultiSelectOption, type MultiSelectProps, Navbar, type NavbarLink, type NavbarProps, type Option, type OptionGroup, Pagination, type PaginationProps, type PolymorphicAs, type PolymorphicComponent, type PolymorphicProps, type PolymorphicPropsWithRef, type PolymorphicRef, Popover, type PopoverProps, Portal, type PortalProps, Pre, type PreProps, Progress, type ProgressProps, Radio, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioProps, Rating, type RatingProps, type ResponsiveColumns, Select, type SelectGroup, type SelectOption, type SelectProps, Sidebar, type SidebarItem, type SidebarProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Spinner, type SpinnerProps, Stack, type StackOwnProps, type StackProps, Stat, type StatProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, type Sx, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextOwnProps, type TextProps, type TextTone, Textarea, type TextareaProps, type Theme, ThemeProvider, type ThemeProviderProps, type ThemeTokens, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastApi, type ToastOptions, type ToastProps, ToastProvider, type ToastProviderProps, type ToastTone, ToastViewport, type ToastViewportProps, type Tone, Tooltip, type TooltipProps, type TreeNode, TreeView, type TreeViewProps, TwicoProvider, type TwicoProviderProps, type UseColorSchemeOptions, type UseFocusTrapOptions, type UseKeyPressOptions, type UseMediaQueryOptions, VisuallyHidden, type VisuallyHiddenProps, createTheme, getColorSchemeScript, runDatatableQuery, useClickOutside, useColorScheme, useControllableState, useCopyToClipboard, useDebouncedCallback, useDebouncedValue, useDisclosure, useEventListener, useFocusTrap, useHover, useId, useIntersectionObserver, useInterval, useIsomorphicLayoutEffect, useKeyPress, useLocalStorage, useMediaQuery, useMounted, usePortal, usePrefersReducedMotion, usePrevious, useScrollLock, useTimeout, useToast, useToggle, useWindowSize };