@sesamehr/react-design-system 2.0.0-beta.6 → 2.0.0-beta.8

package/dist/Button/ActionItem/ActionItem.d.ts

@@ -0,0 +1,40 @@
+export interface ActionItemProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'type'> {
+    /**
+     * The chevron at the end. On by default: the row is drawn with one, and a
+     * row without it is the exception.
+     *
+     * A boolean is configuration, which the architecture rules push back on, and
+     * it earns the exception the same way `OxPopoverContent`'s `showArrow` does.
+     * The alternative is a slot prop with no default, which would make every call
+     * site write the chevron out — the common case paying for the rare one, and
+     * two call sites free to reach for a different glyph.
+     */
+    showChevron?: boolean;
+    dataTestid: string;
+}
+/**
+ * ActionItem — mirrors `@sesame/orxata-core` ActionItem.
+ *
+ * A full-width row that runs an action when pressed: a label that takes the
+ * width, and a chevron at the end saying there is something on the other side
+ * of the press.
+ *
+ * Not a `Button` variant, and not for the reason `IconButton` is not one —
+ * that one wears `.ox-button` for its colours and only redraws the box. This
+ * shares nothing with `Button`: the box is a block that fills its parent and
+ * grows with a label that wraps, where every `Button` is an inline-flex of a
+ * fixed height with `whitespace-nowrap`, and the fill is `brand-50` behind
+ * `brand-500` text, which is none of `Button`'s seven colours.
+ *
+ * **No `asChild`, and that is not an omission.** Both primitives' pass-through
+ * root is built for a component whose entire content is the caller's slot —
+ * `Button` and `Chip` are exactly that. This one owns the chevron, and that
+ * breaks both: Radix's `Slot` throws ("Expected a single React element child
+ * or `Slottable`"), and while `Slottable` answers that here, reka's `Slot` on
+ * the Vue side has no equivalent — it merges onto the first child of the
+ * component's own slot and leaves the chevron as a sibling of the caller's
+ * element. The two sides could not have been made to agree, and a prop that
+ * works on one and silently mis-renders on the other is worse than no prop.
+ * A row that navigates is an `onClick` and a `router.push`.
+ */
+export declare const ActionItem: import('react').ForwardRefExoticComponent<ActionItemProps & import('react').RefAttributes<HTMLButtonElement>>;

package/dist/Button/ActionItem/index.d.ts

@@ -0,0 +1 @@
+export { ActionItem, type ActionItemProps } from './ActionItem.tsx';

package/dist/Data/Table/TableScrollbar/TableScrollbar.d.ts

@@ -1,5 +1,5 @@
 /**
- * The scrollbar a virtualised table draws for itself.
+ * Where a virtualised table's overlay scrollbar goes.
  *
  * Every other table in the system hides its bar: they scroll sideways, the
  * shadows at the edges say there is more, and a bar would be chrome. A list of
@@ -10,8 +10,10 @@
  * the scrollport, and the scrollport has to contain the header, so it always
  * cuts across the column names. This one starts below them.
  *
- * It behaves the way an overlay bar does: out of the way until you scroll or
- * reach for the edge, and gone again shortly after.
+ * The bar itself is `Scrollbar`, which knows nothing about any of that. What is
+ * left here is the arithmetic that is only true of a table, handed over as the
+ * custom properties it reads: the header's height, and the offset between the
+ * scrollport and whichever ancestor the bar is actually positioned in.
  */
 export declare function TableScrollbar(): import("react/jsx-runtime").JSX.Element | null;
 export declare namespace TableScrollbar {

package/dist/Data/Table/hooks/useTableVirtual/useTableVirtual.types.d.ts

@@ -26,9 +26,10 @@ export interface UseTableVirtualOptions {
      * This is what turns a scroll position into a row index, so it is worth
      * getting right: the error is paid on every row crossed, which is nothing at
      * one click of the wheel and hundreds of rows after a flick. The default,
-     * 48px, is the height `TableRow` gives itself with plain text in it. Rows
-     * with an avatar or two lines of text are taller, and those tables should say
-     * so here.
+     * 52px, is `--table-row-height` on `.oxTableRoot` — the minimum a row's cells
+     * give it with plain text in them. (Not `TableRow`'s own CSS: `height` on a
+     * `<tr>` is ignored by the table layout algorithm.) Rows with an avatar or two
+     * lines of text are taller, and those tables should say so here.
      *
      * It is deliberately a number you give rather than one measured from the
      * page. Measuring as you scroll means the total height changes as you scroll,

package/dist/Display/Avatar/AvatarSkeleton/AvatarSkeleton.d.ts

@@ -0,0 +1,30 @@
+import { AvatarSize } from '../index.ts';
+export interface AvatarSkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Matches the avatar's size scale — the placeholder is the same box */
+    size?: AvatarSize;
+    /** Which avatar it stands in for. Only the radius differs. */
+    shape?: 'rounded' | 'square';
+    dataTestid: string;
+}
+/**
+ * An avatar-shaped placeholder, for while the avatar is still loading.
+ *
+ * It renders `OxSkeleton` and wears the *avatar's own* size class, which is why
+ * this is a component and not a documented pair of utilities. `size-12` is what
+ * `md` happens to be today; a caller who wrote that by hand would be holding a
+ * copy of our scale, and it would go quietly wrong the day the scale moved.
+ * Here the placeholder and the real avatar read the same rule in
+ * `../avatarSizes.css`, so they cannot drift.
+ *
+ * **One component, not two.** `AvatarRounded` and `AvatarSquare` are separate
+ * because they differ in substance — a ring, an image, a status bullet, an
+ * action and a label, and two different corner geometries. Strip all of that
+ * out and the only thing left that differs is the radius, so a second component
+ * would be a copy of this one with one class changed. That is the
+ * wrapper-with-no-behaviour that `.claude/rules/component-architecture.md` §11
+ * rejects.
+ *
+ * The pulse and the reduced-motion behaviour are not reimplemented here: they
+ * come from `Skeleton`, which is the only place they are declared.
+ */
+export declare const AvatarSkeleton: import('react').ForwardRefExoticComponent<AvatarSkeletonProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Display/Avatar/index.d.ts

@@ -1,6 +1,8 @@
 import { VariantProps } from 'class-variance-authority';
 export { AvatarRounded } from './AvatarRounded/AvatarRounded.tsx';
 export type { AvatarRoundedProps } from './AvatarRounded/AvatarRounded.tsx';
+export { AvatarSkeleton } from './AvatarSkeleton/AvatarSkeleton.tsx';
+export type { AvatarSkeletonProps } from './AvatarSkeleton/AvatarSkeleton.tsx';
 export { AvatarSquare } from './AvatarSquare/AvatarSquare.tsx';
 export type { AvatarSquareProps } from './AvatarSquare/AvatarSquare.tsx';
 export { useAvatarBullet } from './hooks/useAvatarBullet.ts';

package/dist/Display/ChatBubble/ChatBubble.d.ts

@@ -1,10 +1,27 @@
 import { ReactNode } from 'react';
-import { ChatBubbleVariants } from './index.ts';
+import { ChatBubbleDelivery, ChatBubbleVariants } from './index.ts';
 export interface ChatBubbleProps extends React.HTMLAttributes<HTMLDivElement> {
     /** Who said it: the reader, or someone else */
     author?: ChatBubbleVariants['author'];
-    /** The line under the message — the timestamp, and a receipt if there is one */
-    meta?: ReactNode;
+    /**
+     * When the message went and whether it arrived, drawn as the footer line.
+     *
+     * Each key stands alone, so `{ time }`, `{ status }`, both or neither all
+     * work and an omitted key renders nothing — there is no flag to set and no
+     * line to assemble. Anything this cannot express (a delivery error, an
+     * "edited" marker, an avatar) goes in `footer` instead, which replaces this
+     * line wholesale when both are given.
+     */
+    delivery?: ChatBubbleDelivery;
+    /**
+     * The line under the message, drawn by hand. Ports the Vue `#footer` slot,
+     * and wins over `delivery` when both are supplied.
+     *
+     * Spelled `ReactNode` inline rather than behind an alias because
+     * `orxata/max-props` discounts a slot by reading the type *text*, and an alias
+     * hides it.
+     */
+    footer?: ReactNode;
     dataTestid: string;
 }
 /** ChatBubble — mirrors `@sesame/orxata-core` ChatBubble. */

package/dist/Display/ChatBubble/ChatBubbleStatus/ChatBubbleStatus.d.ts

@@ -1,8 +1,8 @@
 import { ChatBubbleStatusVariants } from './index.ts';
-export interface ChatBubbleStatusProps extends React.SVGAttributes<SVGSVGElement> {
+export interface ChatBubbleStatusProps extends React.HTMLAttributes<HTMLElement> {
     /** How far along the message is */
     status?: NonNullable<ChatBubbleStatusVariants['status']>;
     dataTestid: string;
 }
 /** ChatBubbleStatus — mirrors `@sesame/orxata-core` ChatBubbleStatus. */
-export declare const ChatBubbleStatus: import('react').ForwardRefExoticComponent<ChatBubbleStatusProps & import('react').RefAttributes<SVGSVGElement>>;
+export declare const ChatBubbleStatus: import('react').ForwardRefExoticComponent<ChatBubbleStatusProps & import('react').RefAttributes<HTMLElement>>;

package/dist/Display/ChatBubble/index.d.ts

@@ -1,5 +1,36 @@
 import { VariantProps } from 'class-variance-authority';
+import { ChatBubbleStatusVariants } from './ChatBubbleStatus/index.ts';
 export { ChatBubble, type ChatBubbleProps } from './ChatBubble.tsx';
+/**
+ * When the message went and whether it arrived — the bubble's footer, as data
+ * rather than as markup.
+ *
+ * One object rather than a prop each, for the same reason `ChatInput` takes one
+ * `actionLabels`: the parts belong together, they are all optional, and spending
+ * a prop per part would put a two-field component against the five-prop cap for
+ * no gain. Every key is independent — a time with no receipt, a receipt with no
+ * time, both, or neither — and an omitted key renders nothing at all, so the
+ * four combinations need no flags to select between them.
+ *
+ * Nothing here is prose the design system invents. `time` is a string the caller
+ * has already formatted, because formatting a date needs a locale, a timezone
+ * and a house style, and this package ships no strings and knows none of those.
+ * `status` is not text at all — it is an enum the bubble draws as an icon.
+ */
+export interface ChatBubbleDelivery {
+    /**
+     * The timestamp, already formatted — `'13 mar'`, `'09:41'`, whatever the
+     * product shows. Omit it for a bubble that carries only a receipt.
+     */
+    time?: string;
+    /**
+     * How far along the message is, drawn as a receipt.
+     *
+     * Only your own messages have one: there is no receipt for what somebody else
+     * said, so a bubble with `author: 'other'` normally omits this.
+     */
+    status?: NonNullable<ChatBubbleStatusVariants['status']>;
+}
 /**
  * Who said it, which is the only thing that varies.
  *

package/dist/Display/FileCard/FileCard.d.ts

@@ -0,0 +1,66 @@
+/**
+ * One attached file as a row. Mirrors `@sesame/orxata-core` FileCard.
+ *
+ * Built on `Card` rather than redrawing the shell. The radius, the border and
+ * the white surface are already a component, and the only reason this file has
+ * a stylesheet at all is the row inside it. `flat` is the card the design
+ * draws: border, no lift — `Card`'s `flat` keeps the outline and drops only the
+ * shadow and the glass.
+ *
+ * ### Why `name` and `meta` are props and the other two are nodes
+ *
+ * Sameness is the product for the text, exactly as in `AvatarDetails`: every
+ * file row we ship is two lines at the same sizes and weights, and a node is
+ * where that guarantee goes to die — the first caller to put a link, a badge or
+ * a third line in it ends the point of having the component. `meta` is
+ * deliberately not called `size`: what the second line says is the
+ * application's business ("1,56 MB", "PDF · yesterday", "Uploaded by Ana"), and
+ * naming it after one of those would be a lie the day someone passes another.
+ *
+ * The glyph and the action are the opposite case. Mapping an extension to an
+ * icon is application knowledge — there are hundreds of extensions and we know
+ * none of them — so `icon` takes a node and falls back to a generic file glyph,
+ * which is the one honest thing a design system can draw. And `action` takes a
+ * node because *which* action is not ours either: download, delete, share,
+ * retry, or nothing at all. It also settles the accessible name, which we
+ * cannot supply since the design system ships no strings — whatever the caller
+ * puts there brings its own, and `IconButton` refuses to render without one.
+ *
+ * ### What it deliberately does not do
+ *
+ * **It has no width.** The design pins 300px with `min-width`, `max-width` and
+ * `width`, and that figure belongs to the screen it was drawn on, not to the
+ * component: a card that hardcodes its own width cannot sit in a grid, a
+ * sidebar or a flexible column, and the parent owns external layout. It fills
+ * what it is given. The 72px height stays, because that one is internal — a
+ * list of these has to have rows of equal height, and long names truncate
+ * rather than growing the row.
+ *
+ * **The root is not a button.** It already contains an interactive control, and
+ * a button inside a button is invalid HTML; making the root activate would also
+ * mean inventing a focus and keyboard contract the design has nothing to say
+ * about. A caller who wants the whole row to do something wraps it, or puts a
+ * link in `action`.
+ */
+export interface FileCardProps extends Omit<React.ComponentPropsWithoutRef<'div'>, 'title'> {
+    /** The file's name. Truncates rather than wrapping — the row is a fixed height. */
+    name: string;
+    /**
+     * The second line: whatever the app knows about the file. Size in the
+     * design, but a type, a date or an author read just as well. Omit it and the
+     * row is one line.
+     */
+    meta?: string;
+    /**
+     * The glyph in the ring. Defaults to a generic file — mapping an extension to
+     * an icon is the application's knowledge, not ours.
+     */
+    icon?: React.ReactNode;
+    /**
+     * The one thing you can do to this file. Nothing by default; whatever you put
+     * here brings its own accessible name.
+     */
+    action?: React.ReactNode;
+    dataTestid: string;
+}
+export declare const FileCard: import('react').ForwardRefExoticComponent<FileCardProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Display/FileCard/index.d.ts

@@ -0,0 +1 @@
+export { FileCard, type FileCardProps } from './FileCard.tsx';

package/dist/Display/FilePreviewCard/FilePreviewCard.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A file you can see: a square thumbnail with one line under it. Mirrors
+ * `@sesame/orxata-core` FilePreviewCard.
+ *
+ * The sibling of `FileCard`, and deliberately not a variant of it. They differ
+ * in axis, in padding, in how they take their width and in what they contain —
+ * and, decisively, this one has neither a title nor an action. A `variant` prop
+ * would have to flip the layout *and* switch off the title *and* switch off the
+ * action, which is three configuration props spent hiding the fact that these
+ * are two components. What they genuinely share is the shell, and both get it
+ * the same way: from `Card`.
+ *
+ * ### The image
+ *
+ * `src` and `alt` rather than a node, because there is nothing to compose — it
+ * is one `<img>`, and taking a node would only invite a second one. `alt` is
+ * required and has no default for the usual reason: the design system ships no
+ * strings, and only the caller knows what the picture is of. Pass `""` if it is
+ * genuinely decorative; that is a decision, and it should have to be made.
+ *
+ * Two failure modes, both handled without a state machine. **Not loaded yet**
+ * is a tinted square, so the card holds its shape and reads as a pending
+ * thumbnail instead of a white hole. **Failed to load** swaps the `<img>` for a
+ * generic picture glyph carrying the same `alt` through `role="img"` — the
+ * browser's broken-image icon is neither styleable nor meaningful, and dropping
+ * the `<img>` is the only way to be rid of it. A new `src` clears the flag, so
+ * one bad URL does not poison the ones after it.
+ *
+ * ### Size
+ *
+ * The thumbnail is 150px square from the design, exposed as
+ * `--ox-file-preview-card-size` rather than a prop — a dimension is a style
+ * concern and CSS variables are how this system inherits those. The card itself
+ * has no width at all: it hugs the thumbnail, which is why the design needed no
+ * width on it either.
+ */
+export interface FilePreviewCardProps extends React.ComponentPropsWithoutRef<'div'> {
+    /** The image to show. */
+    src: string;
+    /** What the image is of. Required — pass `""` only if it is decorative. */
+    alt: string;
+    /**
+     * The single line under the thumbnail: "JPG - 937 KB" in the design, but the
+     * app decides what is worth saying.
+     */
+    meta: string;
+    dataTestid: string;
+}
+export declare const FilePreviewCard: import('react').ForwardRefExoticComponent<FilePreviewCardProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Display/FilePreviewCard/index.d.ts

@@ -0,0 +1 @@
+export { FilePreviewCard, type FilePreviewCardProps, } from './FilePreviewCard.tsx';

package/dist/Feedback/Alert/AlertIcon.d.ts

@@ -1,5 +1,5 @@
 export interface AlertIconProps extends React.HTMLAttributes<HTMLDivElement> {
     dataTestid: string;
 }
-/** AlertIcon — renders the variant's default lucide icon, or `children` if provided. */
+/** AlertIcon — renders the variant's default icon, or `children` if provided. */
 export declare const AlertIcon: import('react').ForwardRefExoticComponent<AlertIconProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Feedback/Dialog/DialogBody.d.ts

@@ -0,0 +1,18 @@
+export interface DialogBodyProps extends React.HTMLAttributes<HTMLDivElement> {
+    dataTestid: string;
+}
+/**
+ * DialogBody — mirrors `@sesame/orxata-core` DialogBody. The scrolling region
+ * of a dialog.
+ *
+ * Everything else in the panel — header, footer, steppers, alerts — stays put;
+ * only this scrolls once the panel reaches its `max-height`. It carries no
+ * styling of its own: the declarations that make it the flexible, scrolling
+ * item live on `DialogContent` next to the `max-height` they depend on, since
+ * a body is only a scroll region because the panel is capped and splitting
+ * that pair across two files is how one of them gets changed alone.
+ *
+ * `data-slot` rather than position, so it can sit anywhere among the panel's
+ * children.
+ */
+export declare const DialogBody: import('react').ForwardRefExoticComponent<DialogBodyProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Feedback/Dialog/index.d.ts

@@ -1,5 +1,6 @@
 export { Dialog, type DialogProps } from './Dialog.tsx';
 export { DialogContent, type DialogContentProps } from './DialogContent.tsx';
+export { DialogBody, type DialogBodyProps } from './DialogBody.tsx';
 export { DialogTitle, type DialogTitleProps } from './DialogTitle.tsx';
 export { DialogDescription, type DialogDescriptionProps, } from './DialogDescription.tsx';
 export { DialogOverlay, type DialogOverlayProps } from './DialogOverlay.tsx';

package/dist/Feedback/Popover/PopoverContent.d.ts

@@ -3,5 +3,11 @@ export interface PopoverContentProps extends React.ComponentPropsWithoutRef<type
     showArrow?: boolean;
     dataTestid: string;
 }
-/** PopoverContent — portalled Radix popover content with optional arrow. */
+/**
+ * PopoverContent — portalled Radix popover content with optional arrow.
+ *
+ * `asChild` draws it on the shared `Surface`, which is what keeps a popover
+ * and a select open on the same screen from having different corners. Only the
+ * padding is a popover's own.
+ */
 export declare const PopoverContent: import('react').ForwardRefExoticComponent<PopoverContentProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Feedback/Progress/index.d.ts

@@ -14,6 +14,6 @@ export type { ProgressProps } from './Progress.tsx';
  * The variant is the caller's to say.
  */
 export declare const progressVariants: (props?: ({
-    variant?: "success" | "warning" | "brand" | "error" | null | undefined;
+    variant?: "success" | "error" | "warning" | "brand" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 export type ProgressVariants = VariantProps<typeof progressVariants>;

package/dist/Feedback/Skeleton/Skeleton.d.ts

@@ -0,0 +1,20 @@
+export interface SkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
+    dataTestid: string;
+}
+/**
+ * A block that pulses while the content it stands in for is still loading.
+ *
+ * It configures nothing. One surface, and the caller gives it its shape with
+ * ordinary classes — `h-4 w-48` is a line of text, `size-10 rounded-full` is an
+ * avatar, `h-32 w-full` is a block. A `shape` or `variant` prop would be three
+ * names for three combinations of width, height and radius that CSS already
+ * says better, and it would run out the moment somebody needed a fourth.
+ *
+ * `OxLoader` and `OxProgress` are the other two, and the three are not
+ * interchangeable — see the MDX for which is which.
+ *
+ * `aria-hidden` sits before the spread so a caller who genuinely needs one of
+ * these in the accessibility tree can override it. The region carrying
+ * `aria-busy` is the right level, and that is the caller's.
+ */
+export declare const Skeleton: import('react').ForwardRefExoticComponent<SkeletonProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Feedback/Skeleton/index.d.ts

@@ -0,0 +1,2 @@
+export { Skeleton } from './Skeleton.tsx';
+export type { SkeletonProps } from './Skeleton.tsx';

package/dist/Forms/Field/FieldGroup/FieldGroup.d.ts

@@ -1,4 +1,19 @@
+import { FieldVariant } from '../useFieldGroup.ts';
 export interface FieldGroupProps extends React.HTMLAttributes<HTMLDivElement> {
-    variant?: 'default' | 'error' | 'success' | 'warning';
+    variant?: FieldVariant;
 }
+/**
+ * A label, a control and a message, ordered and wired to each other.
+ *
+ * Two mechanisms, and they are not redundant. The custom properties in the
+ * stylesheet paint whatever is inside — including a consumer's own control,
+ * which never imported anything from here — with no prop drilling. The context
+ * in `useFieldGroup.ts` carries what a custom property cannot: the `id` the
+ * label points `htmlFor` at, the `aria-describedby` that reaches the message,
+ * and the `aria-invalid` that says the control is wrong.
+ *
+ * Ordering is done with direct-child selectors, so the label, the control and
+ * the message have to be direct children of this element. Anything a consumer
+ * wants to wrap around the field goes outside the group, not inside it.
+ */
 export declare const FieldGroup: import('react').ForwardRefExoticComponent<FieldGroupProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Forms/Field/FieldLabel/FieldLabel.d.ts

@@ -1,2 +1,18 @@
 export type FieldLabelProps = React.LabelHTMLAttributes<HTMLLabelElement>;
+/**
+ * The field's label.
+ *
+ * `htmlFor` comes from the surrounding `<OxFieldGroup>` and points at whichever
+ * control claimed the field's id — without it this is a bare `<label>` that
+ * neither wraps a control nor names one, so clicking it focuses nothing and a
+ * screen reader reaching the control announces no name. It is left off
+ * entirely when no control has claimed the id, since a `htmlFor` pointing at
+ * nothing is not an improvement on no `htmlFor`.
+ *
+ * `id` is always there so a composite control — one with several focusable
+ * children, where `htmlFor` has no single target — can name itself with
+ * `aria-labelledby`.
+ *
+ * A `htmlFor` written by the caller comes in `...props` and wins, as it should.
+ */
 export declare const FieldLabel: import('react').ForwardRefExoticComponent<FieldLabelProps & import('react').RefAttributes<HTMLLabelElement>>;

package/dist/Forms/Field/FieldMessage/FieldMessage.d.ts

@@ -1,5 +1,25 @@
+import { FieldVariant } from '../useFieldGroup.ts';
 export interface FieldMessageProps extends React.HTMLAttributes<HTMLDivElement> {
-    message?: string;
-    variant?: 'default' | 'error' | 'success' | 'warning';
+    /**
+     * Overrides the group's variant. Leave it out inside an `<OxFieldGroup>` and
+     * the group's own variant comes through the context, so `error` is written
+     * once instead of on both.
+     */
+    variant?: FieldVariant;
 }
+/**
+ * The field's feedback line.
+ *
+ * `id` comes from the surrounding `<OxFieldGroup>` so the control can point
+ * `aria-describedby` at it. Without one, the error was announced when it
+ * appeared and never again: tab back to a field that is already wrong and
+ * nothing described it.
+ *
+ * `role="alert"` and nothing else. The pair it used to carry — `role="alert"`
+ * with `aria-live="polite"` — contradicted itself, since `alert` already
+ * implies `assertive`. `alert` is the half worth keeping: it is what makes a
+ * message that appears after a submit interrupt, and the case it does not
+ * cover, a field that is *already* wrong when you reach it, is now covered by
+ * `aria-describedby` instead.
+ */
 export declare const FieldMessage: import('react').ForwardRefExoticComponent<FieldMessageProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Forms/Field/index.d.ts

@@ -1,3 +1,4 @@
 export { FieldGroup, type FieldGroupProps } from './FieldGroup/FieldGroup.tsx';
 export { FieldLabel, type FieldLabelProps } from './FieldLabel/FieldLabel.tsx';
 export { FieldMessage, type FieldMessageProps, } from './FieldMessage/FieldMessage.tsx';
+export { useFieldControl, useFieldControlGroup, type FieldControlAttrs, type FieldControlGroupAttrs, type FieldVariant, } from './useFieldGroup.ts';

package/dist/Forms/Field/useFieldGroup.d.ts

@@ -0,0 +1,108 @@
+/**
+ * What a `<OxFieldGroup>` hands to the label, the control and the message
+ * inside it.
+ *
+ * `FieldGroup` already paints its children through custom properties
+ * (`--message-text-color`, `--controller-border-color`), and that stays: it is
+ * what lets a consumer's own control inherit the error colour with no prop
+ * drilling. A custom property cannot carry an `id` or an `aria-invalid`,
+ * though, so the accessible half needs a real context beside it.
+ *
+ * Every piece is optional. A control used on its own — no `FieldGroup`
+ * anywhere above it — gets an empty attribute bag and renders exactly as it
+ * did before, which is why `useFieldGroup` returns `undefined` instead of
+ * throwing the way `useInputPassword` does. There, a subcomponent outside its
+ * root is meaningless; here, a bare `<OxInputText>` is a perfectly good input.
+ *
+ * Nothing emits an IDREF that points at nothing. `aria-describedby` waits for
+ * a message to mount, `aria-labelledby` for a label, and `<label htmlFor>` for
+ * a control to claim the id — a reference to an element that is not there is
+ * worse than no reference, because some readers then announce nothing at all
+ * rather than falling back.
+ */
+export type FieldVariant = 'default' | 'error' | 'success' | 'warning';
+/** The parts of the group that announce themselves so an IDREF never dangles. */
+type FieldPart = 'label' | 'message';
+export interface FieldGroupContextValue {
+    /**
+     * Id on the `<label>`. A composite control — one with several focusable
+     * children, where `htmlFor` has no single target — names itself by pointing
+     * `aria-labelledby` here.
+     */
+    labelId: string;
+    /** Id on the message, and what a control points `aria-describedby` at. */
+    messageId: string;
+    /** What `<label htmlFor>` points at, once a control has claimed it. */
+    controlId: string | undefined;
+    variant: FieldVariant;
+    hasLabel: boolean;
+    hasMessage: boolean;
+    /** Announce a part as mounted. Returns the call that takes it back. */
+    register: (_part: FieldPart) => () => void;
+    /**
+     * Offer an id as the one the label names. The first control to ask gets it;
+     * a second is refused, because one label names one thing.
+     */
+    claimControl: (_id: string) => () => void;
+}
+export interface FieldControlAttrs {
+    id?: string;
+    'aria-invalid'?: true;
+    'aria-describedby'?: string;
+}
+export interface FieldControlGroupAttrs {
+    'aria-labelledby'?: string;
+    'aria-invalid'?: true;
+    'aria-describedby'?: string;
+}
+export interface FieldLabelAttrs {
+    id?: string;
+    htmlFor?: string;
+}
+export declare const FieldGroupContext: import('react').Context<FieldGroupContextValue | null>;
+/**
+ * The surrounding field, or `undefined` when there is none.
+ *
+ * Deliberately not a throwing `useXxx`: the context is optional, so its
+ * absence is not an error.
+ */
+export declare function useFieldGroup(): FieldGroupContextValue | undefined;
+/**
+ * Wiring for a control the `<label>` can point `htmlFor` at — anything
+ * labelable: `input`, `textarea`, `select`, and the `button`s Radix renders
+ * for a checkbox, a switch or a select trigger.
+ *
+ * Spread it *before* `{...props}` so the caller's attributes win over it, and
+ * hand it the caller's own `id`: that is what makes an explicit `id` survive,
+ * with the label following it there rather than staying on the generated one.
+ * Vue's half reads the id out of `useAttrs()` instead — React has no such
+ * channel, so the prop has to be passed in.
+ */
+export declare function useFieldControl(id?: string): FieldControlAttrs;
+/**
+ * Wiring for a composite — `OxRadioGroup`, `OxInputOtp` — where "put the id on
+ * the control" has no single answer because there are several focusable
+ * elements and one id cannot be on all of them.
+ *
+ * It names itself with `aria-labelledby` instead, so the element it goes on
+ * needs a role that takes a name from the author: Radix gives its radio group
+ * `role="radiogroup"`, and anything else has to say `role="group"` itself. On
+ * a plain `<div>` the name is dropped on the floor.
+ */
+export declare function useFieldControlGroup(): FieldControlGroupAttrs;
+/** Wiring for a `<label>` inside the group: its own id, and what it names. */
+export declare function useFieldLabel(): FieldLabelAttrs;
+/**
+ * Wiring for the message: the id a control describes itself with, and the
+ * group's variant so it does not have to be written on both.
+ */
+export declare function useFieldMessage(): {
+    id?: string;
+    variant?: FieldVariant;
+};
+/**
+ * The state a `<OxFieldGroup>` owns. Split out of the component so the ids and
+ * the bookkeeping live next to the hooks that read them.
+ */
+export declare function useProvideFieldGroup(variant: FieldVariant): FieldGroupContextValue;
+export {};

package/dist/Forms/Inputs/Calendar/Calendar.d.ts

@@ -1,5 +1,6 @@
 import { CalendarDayState } from './CalendarDay.tsx';
 import { CalendarConstraints } from './constraints.ts';
+import { CalendarNav } from './nav.ts';
 /** One day. Falls back to `OxCalendarDay`. */
 type DayRenderer = (props: {
     date: Date;
@@ -34,13 +35,7 @@ export interface CalendarProps extends Pick<React.HTMLAttributes<HTMLDivElement>
      * Empty by default. Receives the visible month and the navigation state,
      * because without those nobody could build a header at all.
      */
-    header?: (state: {
-        month: Date;
-        goToPrev: () => void;
-        goToNext: () => void;
-        canGoPrev: boolean;
-        canGoNext: boolean;
-    }) => React.ReactNode;
+    header?: (nav: CalendarNav) => React.ReactNode;
     /**
      * One month's name, above its grid. Falls back to the month and year from
      * `Intl`, and only renders when `months` is more than one — a lone month is

package/dist/Forms/Inputs/Calendar/CalendarRange.d.ts

@@ -1,5 +1,6 @@
 import { CalendarDayState } from './CalendarDay.tsx';
 import { CalendarConstraints } from './constraints.ts';
+import { CalendarNav } from './nav.ts';
 /** One day. Falls back to `OxCalendarDay`. */
 type DayRenderer = (props: {
     date: Date;
@@ -35,13 +36,7 @@ export interface CalendarRangeProps extends Pick<React.HTMLAttributes<HTMLDivEle
      * Empty by default. Receives the visible month and the navigation state,
      * because without those nobody could build a header at all.
      */
-    header?: (state: {
-        month: Date;
-        goToPrev: () => void;
-        goToNext: () => void;
-        canGoPrev: boolean;
-        canGoNext: boolean;
-    }) => React.ReactNode;
+    header?: (nav: CalendarNav) => React.ReactNode;
     /**
      * One month's name, above its grid. Falls back to the month and year from
      * `Intl`, and only renders at all when there is more than one grid — a lone