@ship-it-ui/ui 0.0.13 → 0.0.15

package/dist/index.d.ts

@@ -1,11 +1,10 @@
 import { ClassValue } from 'clsx';
 export { ClassValue } from 'clsx';
 import * as react from 'react';
-import { useEffect, KeyboardEvent, RefObject, ButtonHTMLAttributes, ReactNode, HTMLAttributes, InputHTMLAttributes, TextareaHTMLAttributes, AnchorHTMLAttributes, Ref, MouseEvent, forwardRef, LabelHTMLAttributes, FC, SVGAttributes, MouseEventHandler } from 'react';
+import { ReactElement, ReactNode, ComponentPropsWithoutRef, TimeHTMLAttributes, useEffect, KeyboardEvent, RefObject, ButtonHTMLAttributes, HTMLAttributes, InputHTMLAttributes, TextareaHTMLAttributes, AnchorHTMLAttributes, Ref, MouseEvent, forwardRef, LabelHTMLAttributes, FC, SVGAttributes, MouseEventHandler } from 'react';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
 import * as RadixCheckbox from '@radix-ui/react-checkbox';
-import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as RadixRadio from '@radix-ui/react-radio-group';
 import * as RadixSelect from '@radix-ui/react-select';
 import * as RadixSlider from '@radix-ui/react-slider';
@@ -31,6 +30,103 @@ import * as RadixTabs from '@radix-ui/react-tabs';
  */
 declare function cn(...inputs: ClassValue[]): string;
 
+/**
+ * Emits a `<script type="application/ld+json">` tag carrying schema.org (or
+ * any JSON-serializable) structured data. The payload is escaped so a
+ * user-supplied string containing `</script>` can't break out of the script
+ * tag — that's the standard Next.js JSON-LD recipe.
+ *
+ * Returns `null` for `null`/`undefined` data so call sites can pass the
+ * payload directly without an outer guard.
+ *
+ * @example
+ * <JsonLd data={{
+ *   '@context': 'https://schema.org',
+ *   '@type': 'BreadcrumbList',
+ *   itemListElement: items,
+ * }} />
+ */
+interface JsonLdProps {
+    /** The structured-data payload. JSON-stringified into the script body. */
+    data: unknown;
+}
+declare function JsonLd({ data }: JsonLdProps): ReactElement | null;
+
+/**
+ * Helpers used by components that emit schema.org JSON-LD.
+ *
+ * Centralised here so the seven structured-data components
+ * (ComparisonTable, Breadcrumbs, ReviewCard, Testimonial, PricingCard,
+ * ListingCard/Detail, ConnectorCard) don't each carry their own copy.
+ * If the behavior ever needs to change (e.g. handle `bigint`,
+ * normalise whitespace), there's one place to do it.
+ */
+/**
+ * Returns the string form of a `ReactNode` when it's a plain string or
+ * number, otherwise `null`. Components emitting JSON-LD use this to
+ * decide whether a JSX-typed prop can populate a string-only schema
+ * field — when it returns `null`, the field (or the whole entity) is
+ * skipped rather than coerced to `"[object Object]"` or similar.
+ */
+declare function nodeToString(node: ReactNode): string | null;
+/**
+ * Returns the ISO 8601 string for a `Date`, `string`, or epoch-number
+ * input, or `null` when the value is `undefined`/`null` or the
+ * resulting `Date` is not a valid timestamp. Used by the
+ * `datePublished` / `dateModified` JSON-LD fields and the
+ * `<time dateTime>` attribute on review and activity components.
+ *
+ * Strings are passed through as-is (no validation) so consumers who
+ * already have an ISO 8601 string don't pay for a parse + re-format
+ * round trip and so non-ISO machine-readable strings supported by
+ * `<time dateTime>` (e.g. `"2026-W19"`) survive.
+ */
+declare function toIsoString(value: Date | string | number | undefined | null): string | null;
+
+/**
+ * Six valid HTML heading levels. Components in the design system expose this
+ * type through a `titleAs?: HeadingLevel` prop so consumers can compose the
+ * page's H1/H2/H3 hierarchy correctly.
+ */
+type HeadingLevel = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+interface HeadingProps extends ComponentPropsWithoutRef<'h2'> {
+    /** Heading level to render. Default `'h2'`. */
+    as?: HeadingLevel;
+}
+/**
+ * Renders an `<h1>`–`<h6>` element based on the `as` prop, defaulting to
+ * `<h2>`. Use this in design-system components that surface a `titleAs`
+ * configurable heading prop so the visual style stays consistent while the
+ * underlying element changes.
+ *
+ * @example
+ * <Heading as={titleAs} className="text-[18px] font-semibold">
+ *   {title}
+ * </Heading>
+ */
+declare const Heading: react.ForwardRefExoticComponent<HeadingProps & react.RefAttributes<HTMLHeadingElement>>;
+
+interface DateTimeProps extends Omit<TimeHTMLAttributes<HTMLTimeElement>, 'dateTime' | 'children'> {
+    /** Machine-readable ISO 8601 string or `Date` object. Rendered into `<time dateTime="…">`. */
+    iso: string | Date;
+    /**
+     * Visible label. When omitted the component falls back to the ISO string,
+     * so consumers can pass just `<DateTime iso={...} />` and get a sane render.
+     */
+    children?: ReactNode;
+}
+/**
+ * Wraps a date label in a `<time dateTime="…">` element with a machine-readable
+ * ISO 8601 attribute. Search crawlers and AI agents read `dateTime` for
+ * timestamps even when the visible label is a relative phrase like
+ * "2 days ago" or a localized format like "May 3, 2026".
+ *
+ * @example
+ * <DateTime iso="2026-05-03">May 3, 2026</DateTime>
+ * <DateTime iso={lastSyncedAt}>{formatRelative(lastSyncedAt)}</DateTime>
+ */
+declare const DateTime: react.ForwardRefExoticComponent<DateTimeProps & react.RefAttributes<HTMLTimeElement>>;
+
 /**
  * Standard controlled/uncontrolled state hook. Mirrors Radix's
  * `useControllableState` — when `value` is provided, the hook stays in sync
@@ -154,9 +250,9 @@ declare function useTheme(): {
  * else defers. Variants and sizes match `design-handoff/project/components/Button.jsx`.
  */
 declare const buttonStyles: (props?: ({
-    variant?: "primary" | "secondary" | "ghost" | "outline" | "destructive" | "success" | "link" | null | undefined;
+    variant?: "link" | "primary" | "secondary" | "ghost" | "outline" | "destructive" | "success" | null | undefined;
     size?: "sm" | "md" | "lg" | null | undefined;
-    density?: "comfortable" | "touch" | null | undefined;
+    density?: "touch" | "comfortable" | null | undefined;
     fullWidth?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonStyles> {
@@ -177,7 +273,7 @@ declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAtt
 declare const iconButtonStyles: (props?: ({
     variant?: "primary" | "secondary" | "ghost" | "outline" | "destructive" | "success" | null | undefined;
     size?: "sm" | "md" | "lg" | null | undefined;
-    density?: "comfortable" | "touch" | null | undefined;
+    density?: "touch" | "comfortable" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface IconButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'>, VariantProps<typeof iconButtonStyles> {
     /** The glyph or icon node to render. Pure decoration — set `aria-label` for screen readers. */
@@ -291,7 +387,7 @@ interface FieldProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
  *     {(p) => <Input type="email" placeholder="me@org.com" {...p} />}
  *   </Field>
  */
-declare function Field({ label, hint, error, required, className, children, ...props }: FieldProps): react_jsx_runtime.JSX.Element;
+declare function Field({ label, hint, error, required, className, children, ...props }: FieldProps): react.JSX.Element;
 
 /**
  * Display-to-input rename primitive. Renders `value` as a static element until
@@ -345,7 +441,7 @@ declare const InlineEdit: react.ForwardRefExoticComponent<InlineEditProps & reac
 declare const inputWrapperStyles: (props?: ({
     size?: "sm" | "md" | "lg" | null | undefined;
     tone?: "default" | "err" | null | undefined;
-    density?: "comfortable" | "touch" | null | undefined;
+    density?: "touch" | "comfortable" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'>, VariantProps<typeof inputWrapperStyles> {
     /** Element rendered to the left of the input (an `IconGlyph`, `@`, etc.). */
@@ -504,7 +600,7 @@ interface SelectProps extends Omit<RadixSelect.SelectProps, 'children'> {
  * One-line Select. For composition (groups, separators), use the lower-level
  * `SelectRoot/Trigger/Content/Item` exports directly.
  */
-declare function Select({ options, placeholder, size, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, ...rootProps }: SelectProps): react_jsx_runtime.JSX.Element;
+declare function Select({ options, placeholder, size, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, ...rootProps }: SelectProps): react.JSX.Element;
 
 interface SliderProps extends Omit<RadixSlider.SliderProps, 'asChild' | 'value' | 'defaultValue' | 'onValueChange'> {
     /** Show the numeric value to the right of the track. */
@@ -647,9 +743,9 @@ interface BadgeProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'color'>, Var
 declare const Badge: react.ForwardRefExoticComponent<BadgeProps & react.RefAttributes<HTMLSpanElement>>;
 
 declare const cardStyles: (props?: ({
-    variant?: "ghost" | "default" | "elevated" | null | undefined;
+    variant?: "default" | "ghost" | "elevated" | null | undefined;
     interactive?: boolean | null | undefined;
-    density?: "comfortable" | "touch" | null | undefined;
+    density?: "touch" | "comfortable" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface CardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'>, VariantProps<typeof cardStyles> {
     /** Render a header row with this title (and optional `actions`). */
@@ -944,7 +1040,7 @@ interface DialogProps extends RadixDialog.DialogProps {
     /** When set, content is wrapped in a content frame; omit for full custom layout. */
     children?: ReactNode;
 }
-declare function Dialog({ title, description, footer, width, children, ...rootProps }: DialogProps): react_jsx_runtime.JSX.Element;
+declare function Dialog({ title, description, footer, width, children, ...rootProps }: DialogProps): react.JSX.Element;
 
 type DrawerSide = 'left' | 'right' | 'bottom';
 interface DrawerProps extends RadixDialog.DialogProps {
@@ -1042,7 +1138,7 @@ interface HoverCardProps extends RadixHoverCard.HoverCardProps {
     content: ReactNode;
 }
 /** Convenience wrapper — pass `trigger` and `content` as props. */
-declare function HoverCard({ trigger, content, ...rootProps }: HoverCardProps): react_jsx_runtime.JSX.Element;
+declare function HoverCard({ trigger, content, ...rootProps }: HoverCardProps): react.JSX.Element;
 
 declare const PopoverRoot: react.FC<RadixPopover.PopoverProps>;
 declare const PopoverTrigger: react.ForwardRefExoticComponent<RadixPopover.PopoverTriggerProps & react.RefAttributes<HTMLButtonElement>>;
@@ -1086,7 +1182,7 @@ interface ToastContextValue {
  */
 declare function ToastProvider({ children }: {
     children: ReactNode;
-}): react_jsx_runtime.JSX.Element;
+}): react.JSX.Element;
 declare function useToast(): ToastContextValue;
 interface ToastCardProps {
     toast: ToastEntry;
@@ -1132,7 +1228,7 @@ interface SimpleTooltipProps {
  * (multiple triggers in a list, shared delay config), use the lower-level
  * `Tooltip` + `TooltipTrigger` + `TooltipContent` primitives.
  */
-declare function SimpleTooltip({ content, children, side, delayDuration, }: SimpleTooltipProps): react_jsx_runtime.JSX.Element;
+declare function SimpleTooltip({ content, children, side, delayDuration, }: SimpleTooltipProps): react.JSX.Element;
 
 /**
  * Alert — inline messaging block. Four tones (accent / ok / warn / err) with a
@@ -1200,10 +1296,19 @@ declare const Banner: react.ForwardRefExoticComponent<BannerProps & react.RefAtt
  * the current page (rendered as plain text with `aria-current="page"`); earlier
  * crumbs render as links if `href` is provided. Pass `separator` to swap the
  * default `/` divider.
+ *
+ * Emits a schema.org `BreadcrumbList` JSON-LD script next to the `<nav>` so
+ * crawlers and AI agents understand the trail without parsing the DOM. The
+ * script auto-derives `position`/`name`/`item` from each `<Crumb>`'s `href`
+ * and visible children; crumbs without a string label are skipped. Pass
+ * `noStructuredData` to suppress emission entirely (consumers emitting their
+ * own page-level structured data).
  */
 interface BreadcrumbsProps extends HTMLAttributes<HTMLElement> {
     /** Element to render between crumbs. Defaults to a dim `/`. */
     separator?: ReactNode;
+    /** Opt out of emitting the `BreadcrumbList` JSON-LD script. */
+    noStructuredData?: boolean;
 }
 declare const Breadcrumbs: react.ForwardRefExoticComponent<BreadcrumbsProps & react.RefAttributes<HTMLElement>>;
 interface CrumbProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
@@ -1371,6 +1476,113 @@ declare const CommandPalette: react.ForwardRefExoticComponent<CommandPaletteProp
  */
 declare function filterCommandItems(query: string, groups: ReadonlyArray<CommandPaletteGroup>): CommandPaletteGroup[];
 
+/**
+ * ComparisonTable — option-vs-option matrix. Rows are features, columns are
+ * options (products, plan tiers, spec sheets), cells are booleans (rendered as
+ * check/cross with sr-only "Yes"/"No"), strings, numbers, or `{ value, note }`
+ * objects for a primary value with a small footnote.
+ *
+ * Designed for AI/SEO consumption: emits a `<script type="application/ld+json">`
+ * next to the table by default — one schema.org entity per option, with each
+ * row contributing an `additionalProperty` `PropertyValue`. Pass `schema` to
+ * change the `@type` (default `Product`), or `noStructuredData` to suppress
+ * the script entirely.
+ *
+ * Semantic HTML: `<caption>` (sr-only), `<th scope="col">` for option headers,
+ * `<th scope="row">` for feature names, optional `<tfoot>` for CTA actions.
+ * Featured columns carry `data-featured="true"`; every cell carries
+ * `data-cell-type` and (when meaningful) `data-cell-value` for crawlers and
+ * scrapers that don't execute JS.
+ */
+type ComparisonCellValue = boolean | string | number | {
+    value: ReactNode;
+    note?: ReactNode;
+};
+interface ComparisonOption {
+    /** Stable key — must match the keys used in each `ComparisonRow.values`. */
+    id: string;
+    /** Visible column header. */
+    name: ReactNode;
+    /** Used as the JSON-LD `name` when `name` is JSX. Falls back to `name` if it's a string. */
+    schemaName?: string;
+    /**
+     * Short description, rendered as a muted line under the name AND used as the
+     * JSON-LD `description`.
+     */
+    description?: ReactNode;
+    /** JSON-LD `url`. */
+    url?: string;
+    /**
+     * Short eyebrow line rendered above the name (uppercase mono). Use for labels
+     * like `STARTER` or `MOST POPULAR` that should live above the tier name
+     * itself.
+     */
+    tagline?: ReactNode;
+    /**
+     * Inline glyph rendered before the name. Pass a `GlyphName` string for a
+     * type-checked icon from the design-system manifest, or any `ReactNode` for
+     * custom imagery (brand logos, avatars).
+     */
+    icon?: GlyphName | ReactNode;
+    /** Highlight as the recommended option — accent-tinted column + auto badge. */
+    featured?: boolean;
+    /** Override the auto "recommended" badge. Set to `null` to suppress entirely. */
+    badge?: ReactNode;
+    /** Optional CTA rendered in a `<tfoot>` row when any option provides one. */
+    action?: ReactNode;
+}
+interface ComparisonRow {
+    /** Visible row header (`<th scope="row">`). */
+    feature: ReactNode;
+    /** Used as the JSON-LD `PropertyValue.name` when `feature` is JSX. */
+    schemaName?: string;
+    /** Small muted line rendered under the feature name. */
+    description?: ReactNode;
+    /** Optional grouping label — sibling rows with the same `group` cluster together. */
+    group?: string;
+    /** Cell values keyed by `ComparisonOption.id`. */
+    values: Record<string, ComparisonCellValue | undefined>;
+}
+type ComparisonSchemaType = 'Product' | 'Service' | 'SoftwareApplication' | (string & {});
+interface ComparisonTableProps {
+    /** Columns. */
+    options: ReadonlyArray<ComparisonOption>;
+    /** Rows. */
+    rows: ReadonlyArray<ComparisonRow>;
+    /** Visible-to-AT caption. Also used as the JSON-LD comparison `name`. */
+    caption: ReactNode;
+    /** schema.org `@type` per option in JSON-LD. Default `'Product'`. */
+    schema?: ComparisonSchemaType;
+    /** Opt out of emitting the JSON-LD `<script>`. */
+    noStructuredData?: boolean;
+    /** Visual density. Default `'comfortable'`. */
+    density?: 'comfortable' | 'compact';
+    /** Sticky table header (requires the table to live in a scroll container). */
+    stickyHeader?: boolean;
+    /**
+     * Option-name text scale in the header. `'sm'` for dense spec sheets,
+     * `'lg'` for marketing pricing-tier tables. Default `'md'`.
+     */
+    headerSize?: 'sm' | 'md' | 'lg';
+    /**
+     * Horizontal alignment for option columns — affects both the header cell
+     * and data cells in option columns. The row-header (feature-name) column
+     * always stays left-aligned. Default `'left'`.
+     */
+    headerAlign?: 'left' | 'center';
+    /**
+     * Lift the featured column visually: stronger header background, top + side
+     * accent borders, larger padding, and a soft shadow. Pair with
+     * `headerAlign="center"` and `headerSize="lg"` for a PricingCard-style tier
+     * comparison.
+     */
+    prominentFeatured?: boolean;
+    className?: string;
+}
+declare function ComparisonTable(props: ComparisonTableProps & {
+    ref?: Ref<HTMLTableElement>;
+}): react.JSX.Element;
+
 /**
  * DataTable — generic, sortable, selectable table. The component is a
  * "headless-with-defaults": you bring your data and column definitions, the
@@ -1423,7 +1635,7 @@ interface DataTableProps<T> {
 }
 declare function DataTable<T>(props: DataTableProps<T> & {
     ref?: Ref<HTMLTableElement>;
-}): react_jsx_runtime.JSX.Element;
+}): react.JSX.Element;
 
 /** A `{from, to}` date range used by `Calendar` and `DateRangePicker`. */
 interface DateRange {
@@ -1590,9 +1802,10 @@ interface ListingCardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'childre
     /**
      * Wrap the photo carousel past the boundaries (next from the last
      * photo goes to the first). Default `true` — marketplace photo
-     * browsing expects looping. Pass `false` to restore stop-at-end.
+     * browsing expects looping. Pass `false` to restore stop-at-end, or
+     * `'circular'` / `'sweep'` to pick the loop variant explicitly.
      */
-    loop?: boolean;
+    loop?: boolean | 'circular' | 'sweep';
     /** Listing title — e.g. "Sun-soaked cabin in Marin". */
     title: ReactNode;
     /** Optional eyebrow text above the title (location, listing type). */
@@ -1647,6 +1860,32 @@ interface ListingCardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'childre
     cta?: ListingCardCta;
     /** Hide the photo counter overlay in `spec` variant. Default `false`. */
     hidePhotoCounter?: boolean;
+    /**
+     * schema.org `@type` for the JSON-LD entity. Defaults to `'Accommodation'`
+     * for the default variant and `'Product'` for the spec variant. Pass
+     * `'Place'`, `'LodgingBusiness'`, or any string to override.
+     */
+    schema?: 'Accommodation' | 'Product' | 'Place' | 'LodgingBusiness' | (string & {});
+    /**
+     * ISO 4217 currency code (e.g. `'USD'`). REQUIRED to emit the `offers`
+     * block — without it the offer is skipped (the rest of the entity still
+     * emits if `title` resolves to a string).
+     */
+    priceCurrency?: string;
+    /**
+     * Explicit numeric price for JSON-LD. When omitted, parsed from the
+     * visible `price` prop by stripping non-numeric characters. Pass this
+     * when `price` is JSX or not cleanly parseable.
+     */
+    priceAmount?: number;
+    /** Optional URL of the listing detail page — also emitted as the entity `url`. */
+    url?: string;
+    /** String version of `title` for the JSON-LD `name`. Required if `title` is JSX. */
+    titleText?: string;
+    /** String version of `eyebrow` for the JSON-LD `description`. */
+    descriptionText?: string;
+    /** Opt out of emitting the JSON-LD script. */
+    noStructuredData?: boolean;
     /**
      * Per-section className overrides. Each key targets a specific element in
      * the rendered tree; values are merged with the component's own utilities
@@ -1751,9 +1990,11 @@ interface ListingDetailProps {
      * Wrap the gallery carousel and the fullscreen lightbox past the
      * boundaries (next from the last photo goes to the first). Default
      * `true` — marketplace photo browsing expects looping. One prop
-     * drives both surfaces.
+     * drives both surfaces. Pass `'circular'` or `'sweep'` to pick the
+     * gallery's loop variant explicitly; both forward as truthy to the
+     * lightbox.
      */
-    loop?: boolean;
+    loop?: boolean | 'circular' | 'sweep';
     /** Listing title — e.g. "Sun-soaked cabin in Marin". */
     title: ReactNode;
     /** Optional eyebrow above the title — listing type, location. */
@@ -1792,6 +2033,35 @@ interface ListingDetailProps {
     cta?: ListingCardCta;
     /** Hide the photo counter overlay in `spec` variant. Default `false`. */
     hidePhotoCounter?: boolean;
+    /**
+     * schema.org `@type` for the JSON-LD entity. Defaults to `'Accommodation'`
+     * for the default variant and `'Product'` for the spec variant. Pass
+     * `'Place'`, `'LodgingBusiness'`, or any custom string to override.
+     */
+    schema?: 'Accommodation' | 'Product' | 'Place' | 'LodgingBusiness' | (string & {});
+    /**
+     * ISO 4217 currency code (e.g. `'USD'`). REQUIRED to emit the `offers`
+     * block — without it the offer is skipped (the rest of the entity still
+     * emits if `title` resolves to a string).
+     */
+    priceCurrency?: string;
+    /**
+     * Explicit numeric price for JSON-LD. When omitted, parsed from the
+     * visible `price` prop by stripping non-numeric characters.
+     */
+    priceAmount?: number;
+    /** Listing detail URL, also emitted as the entity `url`. */
+    url?: string;
+    /** String version of `title` for the JSON-LD `name`. Required if `title` is JSX. */
+    titleText?: string;
+    /** String version of `description` for the JSON-LD `description`. */
+    descriptionText?: string;
+    /**
+     * Opt out of emitting the JSON-LD `<script>`. The script renders as a
+     * sibling of the Radix Dialog root (outside the Portal) so it appears in
+     * the SSR'd HTML regardless of `open` state — crawlers see it always.
+     */
+    noStructuredData?: boolean;
     /**
      * Per-section className overrides. Each key targets a specific element
      * in the rendered tree; values are merged with the component's own
@@ -1932,6 +2202,14 @@ declare const PriceBreakdownLine: react.ForwardRefExoticComponent<PriceBreakdown
  * body, optional photos strip, and a `verified-trip` badge.
  *
  * Distinct from `Testimonial`, which is curated marketing chrome.
+ *
+ * Emits a schema.org `Review` JSON-LD entity by default. Pass `dateTime`
+ * (ISO 8601 string or Date) to populate `datePublished` and emit a
+ * machine-readable `<time dateTime>`; without it the visible `date` is
+ * still rendered but `datePublished` is omitted. The review must point
+ * at *something* — pass `itemReviewedName` (and optionally `url` of the
+ * reviewed item) so Google's Rich Results Test accepts it as a valid
+ * `Review`. Pass `noStructuredData` to suppress the JSON-LD script.
  */
 interface ReviewCardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
     /** Reviewer display name. */
@@ -1942,6 +2220,13 @@ interface ReviewCardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children
     rating: number;
     /** When set, renders as a Date — otherwise as a string. */
     date: ReactNode;
+    /**
+     * Machine-readable ISO 8601 string (or Date) for the review date. Emitted
+     * as `<time dateTime="…">{date}</time>` and threaded into the JSON-LD
+     * `datePublished` field. Backwards-compatible: when omitted the visible
+     * `date` is rendered without a `dateTime` attribute.
+     */
+    dateTime?: string | Date;
     /** Review body. */
     body: ReactNode;
     /** Optional photo URLs (rendered as a horizontal strip). */
@@ -1950,6 +2235,19 @@ interface ReviewCardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children
     verified?: boolean;
     /** Optional reviewer subtitle (location, member-since date). */
     subtitle?: ReactNode;
+    /**
+     * String version of `author` for the JSON-LD `author.name` field. Required
+     * when `author` is JSX — without it the JSON-LD script is suppressed.
+     */
+    authorName?: string;
+    /** String version of `body` for the JSON-LD `reviewBody`. */
+    bodyText?: string;
+    /** Name of the thing being reviewed (product, place, service). */
+    itemReviewedName?: string;
+    /** Optional URL of the reviewed item. */
+    url?: string;
+    /** Opt out of emitting the schema.org `Review` JSON-LD script. */
+    noStructuredData?: boolean;
 }
 declare const ReviewCard: react.ForwardRefExoticComponent<ReviewCardProps & react.RefAttributes<HTMLDivElement>>;
 
@@ -2009,6 +2307,12 @@ interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'>
     icon?: ReactNode;
     /** Title heading. */
     title: ReactNode;
+    /**
+     * Heading level for the title. Default `'h3'` — EmptyState typically lives
+     * inside a section that already has an `h2`. Bump to `h2` for top-of-screen
+     * "nothing here" states.
+     */
+    titleAs?: HeadingLevel;
     /** Body description. */
     description?: ReactNode;
     /** Optional primary action (e.g., a Button) below the description. */
@@ -2167,6 +2471,11 @@ declare const HealthScore: react.ForwardRefExoticComponent<HealthScoreProps & re
 interface LargeTitleProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
     /** Headline text. */
     title: ReactNode;
+    /**
+     * Heading level for the title. Default `'h1'` — this component is intended
+     * as a screen-level header. Lower to `h2`/`h3` for nested usage.
+     */
+    titleAs?: HeadingLevel;
     /** Optional eyebrow label rendered above the title. Small, uppercase, mono. */
     eyebrow?: ReactNode;
     /** Optional right-aligned slot (avatar, settings button, etc.). */
@@ -2371,7 +2680,7 @@ type NavItemProps = NavItemBaseProps & (({
 } & Omit<HTMLAttributes<HTMLAnchorElement>, keyof NavItemBaseProps>) | ({
     href?: undefined;
 } & Omit<ButtonHTMLAttributes<HTMLButtonElement>, keyof NavItemBaseProps>));
-declare const NavItem: react.ForwardRefExoticComponent<NavItemProps & react.RefAttributes<HTMLButtonElement | HTMLAnchorElement>>;
+declare const NavItem: react.ForwardRefExoticComponent<NavItemProps & react.RefAttributes<HTMLAnchorElement | HTMLButtonElement>>;
 interface NavSectionProps extends HTMLAttributes<HTMLDivElement> {
     /** Eyebrow heading. Rendered uppercase, mono, dim. */
     label: ReactNode;
@@ -2543,6 +2852,12 @@ interface TimelineEvent {
     description?: ReactNode;
     /** Time label rendered in mono. */
     time?: ReactNode;
+    /**
+     * Machine-readable ISO 8601 string or `Date` for the event. When set, the
+     * visible `time` is wrapped in `<time dateTime="…">` so crawlers and AI
+     * agents get a timestamp without parsing the label.
+     */
+    dateTime?: string | Date;
     /** Marker color tone. Defaults to `accent`. */
     tone?: TimelineEventTone;
 }
@@ -2555,6 +2870,11 @@ interface TimelineItemProps extends HTMLAttributes<HTMLLIElement> {
     tone?: TimelineEventTone;
     description?: ReactNode;
     time?: ReactNode;
+    /**
+     * Machine-readable ISO 8601 string or `Date`. When set, the visible `time`
+     * is wrapped in `<time dateTime="…">`.
+     */
+    dateTime?: string | Date;
 }
 declare const TimelineItem: react.ForwardRefExoticComponent<TimelineItemProps & react.RefAttributes<HTMLLIElement>>;
 
@@ -2617,6 +2937,12 @@ declare const ActivityTimeline: react.ForwardRefExoticComponent<ActivityTimeline
 interface TopbarProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
     /** Title rendered on the left. */
     title?: ReactNode;
+    /**
+     * Heading level for the page title. Default `'h1'` on touch density (mobile
+     * page header) and `'h2'` on desktop density (in-app chrome where the page
+     * `h1` typically lives in a separate hero/content area).
+     */
+    titleAs?: HeadingLevel;
     /**
      * Eyebrow label rendered above the title (small uppercase mono). Touch density
      * only — silently ignored on desktop density to avoid two header tiers stacking.
@@ -2740,4 +3066,4 @@ interface WizardDialogProps {
 }
 declare const WizardDialog: react.ForwardRefExoticComponent<WizardDialogProps & react.RefAttributes<HTMLDivElement>>;
 
-export { Accordion, AccordionContent, type AccordionContentProps, AccordionItem, type AccordionItemProps, type AccordionProps, AccordionTrigger, type AccordionTriggerProps, type ActivityActor, type ActivityEvent, ActivityTimeline, type ActivityTimelineProps, Alert, AlertDialog, AlertDialogAction, AlertDialogCancel, type AlertDialogProps, AlertDialogRoot, AlertDialogTrigger, type AlertProps, type AlertTone, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, type AvatarStatus, Badge, type BadgeProps, Banner, type BannerProps, type BannerTone, Breadcrumbs, type BreadcrumbsProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, Calendar, type CalendarProps, Card, CardLink, type CardLinkProps, type CardProps, Carousel, type CarouselProps, Checkbox, type CheckboxProps, Chip, type ChipProps, Combobox, type ComboboxOption, type ComboboxProps, CommandPalette, type CommandPaletteGroup, type CommandPaletteItem, type CommandPaletteProps, ContextMenu, ContextMenuContent, ContextMenuItem, type ContextMenuItemProps, ContextMenuPortal, ContextMenuRoot, ContextMenuSeparator, ContextMenuTrigger, Crumb, type CrumbProps, DataTable, type DataTableColumn, type DataTableProps, type DataTableSort, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, Dialog, DialogClose, DialogContent, type DialogContentProps, DialogOverlay, DialogPortal, type DialogProps, DialogRoot, DialogTrigger, Dots, type DotsProps, Drawer, type DrawerProps, type DrawerSide, DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRoot, DropdownMenuTrigger, Dropzone, type DropzoneProps, EmptyState, type EmptyStateProps, FAB, type FABProps, Field, type FieldProps, FileChip, type FileChipProps, type FilterFacet, type FilterFacetOption, FilterPanel, type FilterPanelProps, type FilterPanelValue, HealthScore, type HealthScoreBreakdownEntry, type HealthScoreProps, HoverCard, HoverCardContent, HoverCardPortal, type HoverCardProps, HoverCardRoot, HoverCardTrigger, IconButton, type IconButtonProps, InlineEdit, type InlineEditHandle, type InlineEditProps, Input, type InputProps, Kbd, type KbdProps, LargeTitle, type LargeTitleProps, Lightbox, type LightboxProps, ListingCard, type ListingCardCta, type ListingCardFlag, type ListingCardProps, type ListingCardSpec, type ListingCardVariant, ListingDetail, type ListingDetailAction, type ListingDetailFeature, type ListingDetailHost, type ListingDetailProps, type ListingDetailVariant, MenuCheckboxItem, MenuItem, type MenuItemProps, MenuSeparator, Menubar, MenubarContent, MenubarItem, type MenubarItemProps, MenubarMenu, MenubarSeparator, MenubarTrigger, NavBar, type NavBarItem, type NavBarOrientation, type NavBarProps, NavItem, type NavItemProps, NavSection, type NavSectionProps, type NormalizedOption, NumberInput, type NumberInputProps, OTP, type OTPHandle, type OTPProps, OnboardingChecklist, type OnboardingChecklistProps, type OnboardingItem, type OnboardingItemStatus, Pagination, type PaginationProps, type PhoneCountry, PhoneInput, type PhoneInputProps, Popover, PopoverAnchor, PopoverArrow, PopoverClose, PopoverContent, PopoverPortal, PopoverRoot, PopoverTrigger, PriceBreakdown, type PriceBreakdownItem, PriceBreakdownLine, type PriceBreakdownLineProps, type PriceBreakdownProps, Progress, type ProgressProps, PullToRefresh, type PullToRefreshProps, type PullToRefreshState, RadialProgress, type RadialProgressProps, type RadialTone, Radio, RadioGroup, type RadioGroupProps, type RadioProps, Rating, type RatingProps, ReviewCard, type ReviewCardProps, ScrollArea, type ScrollAreaProps, type ScrollAreaType, SearchInput, type SearchInputProps, SegmentedControl, type SegmentedControlOption, type SegmentedControlProps, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, type SelectOption, type SelectProps, SelectRoot, SelectTrigger, SelectValue, Sheet, type SheetProps, Sidebar, type SidebarProps, SimpleTooltip, type SimpleTooltipProps, Skeleton, SkeletonGroup, type SkeletonGroupProps, type SkeletonProps, Slider, type SliderProps, Sparkline, type SparklineProps, Spinner, type SpinnerProps, SplitButton, type SplitButtonProps, StatCard, type StatCardProps, type StatTrend, StatusDot, type StatusDotProps, type StatusState, type StepState, Stepper, type StepperProps, type StepperStep, Switch, type SwitchProps, Tab, TabBar, type TabBarItem, type TabBarProps, type TabProps, Tabs, TabsContent, TabsList, type TabsProps, type TabsVariantProps, Tag, type TagProps, Textarea, type TextareaProps, type Theme, Timeline, type TimelineEvent, type TimelineEventTone, TimelineItem, type TimelineItemProps, type TimelineProps, ToastCard, type ToastInput, ToastProvider, type ToastVariant, Tooltip, TooltipArrow, TooltipContent, TooltipPortal, TooltipProvider, TooltipTrigger, Topbar, type TopbarProps, Tree, type TreeItem, type TreeProps, type UseControllableStateProps, type UseKeyboardListOptions, type UseKeyboardListResult, type WizardContext, WizardDialog, type WizardDialogProps, type WizardStep, badgeStyles, buttonStyles, cardStyles, cn, filterCommandItems, formatRelative, iconButtonStyles, phoneCountries, useControllableState, useDisclosure, useEscape, useIsomorphicLayoutEffect, useKeyboardList, useOutsideClick, useTheme, useToast };
+export { Accordion, AccordionContent, type AccordionContentProps, AccordionItem, type AccordionItemProps, type AccordionProps, AccordionTrigger, type AccordionTriggerProps, type ActivityActor, type ActivityEvent, ActivityTimeline, type ActivityTimelineProps, Alert, AlertDialog, AlertDialogAction, AlertDialogCancel, type AlertDialogProps, AlertDialogRoot, AlertDialogTrigger, type AlertProps, type AlertTone, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, type AvatarStatus, Badge, type BadgeProps, Banner, type BannerProps, type BannerTone, Breadcrumbs, type BreadcrumbsProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, Calendar, type CalendarProps, Card, CardLink, type CardLinkProps, type CardProps, Carousel, type CarouselProps, Checkbox, type CheckboxProps, Chip, type ChipProps, Combobox, type ComboboxOption, type ComboboxProps, CommandPalette, type CommandPaletteGroup, type CommandPaletteItem, type CommandPaletteProps, type ComparisonCellValue, type ComparisonOption, type ComparisonRow, type ComparisonSchemaType, ComparisonTable, type ComparisonTableProps, ContextMenu, ContextMenuContent, ContextMenuItem, type ContextMenuItemProps, ContextMenuPortal, ContextMenuRoot, ContextMenuSeparator, ContextMenuTrigger, Crumb, type CrumbProps, DataTable, type DataTableColumn, type DataTableProps, type DataTableSort, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, DateTime, type DateTimeProps, Dialog, DialogClose, DialogContent, type DialogContentProps, DialogOverlay, DialogPortal, type DialogProps, DialogRoot, DialogTrigger, Dots, type DotsProps, Drawer, type DrawerProps, type DrawerSide, DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRoot, DropdownMenuTrigger, Dropzone, type DropzoneProps, EmptyState, type EmptyStateProps, FAB, type FABProps, Field, type FieldProps, FileChip, type FileChipProps, type FilterFacet, type FilterFacetOption, FilterPanel, type FilterPanelProps, type FilterPanelValue, Heading, type HeadingLevel, type HeadingProps, HealthScore, type HealthScoreBreakdownEntry, type HealthScoreProps, HoverCard, HoverCardContent, HoverCardPortal, type HoverCardProps, HoverCardRoot, HoverCardTrigger, IconButton, type IconButtonProps, InlineEdit, type InlineEditHandle, type InlineEditProps, Input, type InputProps, JsonLd, type JsonLdProps, Kbd, type KbdProps, LargeTitle, type LargeTitleProps, Lightbox, type LightboxProps, ListingCard, type ListingCardCta, type ListingCardFlag, type ListingCardProps, type ListingCardSpec, type ListingCardVariant, ListingDetail, type ListingDetailAction, type ListingDetailFeature, type ListingDetailHost, type ListingDetailProps, type ListingDetailVariant, MenuCheckboxItem, MenuItem, type MenuItemProps, MenuSeparator, Menubar, MenubarContent, MenubarItem, type MenubarItemProps, MenubarMenu, MenubarSeparator, MenubarTrigger, NavBar, type NavBarItem, type NavBarOrientation, type NavBarProps, NavItem, type NavItemProps, NavSection, type NavSectionProps, type NormalizedOption, NumberInput, type NumberInputProps, OTP, type OTPHandle, type OTPProps, OnboardingChecklist, type OnboardingChecklistProps, type OnboardingItem, type OnboardingItemStatus, Pagination, type PaginationProps, type PhoneCountry, PhoneInput, type PhoneInputProps, Popover, PopoverAnchor, PopoverArrow, PopoverClose, PopoverContent, PopoverPortal, PopoverRoot, PopoverTrigger, PriceBreakdown, type PriceBreakdownItem, PriceBreakdownLine, type PriceBreakdownLineProps, type PriceBreakdownProps, Progress, type ProgressProps, PullToRefresh, type PullToRefreshProps, type PullToRefreshState, RadialProgress, type RadialProgressProps, type RadialTone, Radio, RadioGroup, type RadioGroupProps, type RadioProps, Rating, type RatingProps, ReviewCard, type ReviewCardProps, ScrollArea, type ScrollAreaProps, type ScrollAreaType, SearchInput, type SearchInputProps, SegmentedControl, type SegmentedControlOption, type SegmentedControlProps, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, type SelectOption, type SelectProps, SelectRoot, SelectTrigger, SelectValue, Sheet, type SheetProps, Sidebar, type SidebarProps, SimpleTooltip, type SimpleTooltipProps, Skeleton, SkeletonGroup, type SkeletonGroupProps, type SkeletonProps, Slider, type SliderProps, Sparkline, type SparklineProps, Spinner, type SpinnerProps, SplitButton, type SplitButtonProps, StatCard, type StatCardProps, type StatTrend, StatusDot, type StatusDotProps, type StatusState, type StepState, Stepper, type StepperProps, type StepperStep, Switch, type SwitchProps, Tab, TabBar, type TabBarItem, type TabBarProps, type TabProps, Tabs, TabsContent, TabsList, type TabsProps, type TabsVariantProps, Tag, type TagProps, Textarea, type TextareaProps, type Theme, Timeline, type TimelineEvent, type TimelineEventTone, TimelineItem, type TimelineItemProps, type TimelineProps, ToastCard, type ToastInput, ToastProvider, type ToastVariant, Tooltip, TooltipArrow, TooltipContent, TooltipPortal, TooltipProvider, TooltipTrigger, Topbar, type TopbarProps, Tree, type TreeItem, type TreeProps, type UseControllableStateProps, type UseKeyboardListOptions, type UseKeyboardListResult, type WizardContext, WizardDialog, type WizardDialogProps, type WizardStep, badgeStyles, buttonStyles, cardStyles, cn, filterCommandItems, formatRelative, iconButtonStyles, nodeToString, phoneCountries, toIsoString, useControllableState, useDisclosure, useEscape, useIsomorphicLayoutEffect, useKeyboardList, useOutsideClick, useTheme, useToast };