@sesamehr/react-design-system 1.6.1 → 2.0.0-beta.10

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

@@ -0,0 +1,28 @@
+import { ReactNode } from 'react';
+import { ChatBubbleDelivery, ChatBubbleVariants } from './index.ts';
+export interface ChatBubbleProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Who said it: the reader, or someone else */
+    author?: ChatBubbleVariants['author'];
+    /**
+     * 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. */
+export declare const ChatBubble: import('react').ForwardRefExoticComponent<ChatBubbleProps & import('react').RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,8 @@
+import { ChatBubbleStatusVariants } from './index.ts';
+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<HTMLElement>>;

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

@@ -0,0 +1,10 @@
+import { VariantProps } from 'class-variance-authority';
+export { ChatBubbleStatus, type ChatBubbleStatusProps, } from './ChatBubbleStatus.tsx';
+/**
+ * How far along a sent message is. Only the reader's own messages carry one —
+ * there is no receipt for what somebody else said.
+ */
+export declare const chatBubbleStatusVariants: (props?: ({
+    status?: "pending" | "sent" | "delivered" | "read" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export type ChatBubbleStatusVariants = VariantProps<typeof chatBubbleStatusVariants>;

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

@@ -0,0 +1,44 @@
+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.
+ *
+ * The design draws a `Hover` state too, and it holds exactly one thing: a
+ * circled chevron for the message's actions menu. That is out of scope here, so
+ * hover has nothing left to change and the component does not pretend it does.
+ */
+export declare const chatBubbleVariants: (props?: ({
+    author?: "other" | "user" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export type ChatBubbleVariants = VariantProps<typeof chatBubbleVariants>;

package/dist/Display/Chip/Chip.d.ts

@@ -1,8 +1,24 @@
 import { ChipVariants } from './index.ts';
-export interface ChipProps extends React.HTMLAttributes<HTMLSpanElement> {
-    /** Which semantic colour it is tinted with */
-    tone?: ChipVariants['tone'];
+export interface ChipProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'type'> {
+    /** How tall it is, and whether it holds a label or a single icon */
+    size?: ChipVariants['size'];
+    /** How its corners are cut */
+    shape?: ChipVariants['shape'];
+    /**
+     * Whether it is being dragged.
+     *
+     * Of the four states the design draws, this is the only one the browser
+     * cannot tell us about on its own: rest, hover and focus are `:hover` and
+     * `:focus-visible`, and there is no `:dragging`.
+     */
+    dragged?: boolean;
+    /** Render as the child element instead of a `<button>` (Radix Slot). */
+    asChild?: boolean;
     dataTestid: string;
 }
-/** Chip — mirrors `@sesame/orxata-core` Chip. */
-export declare const Chip: import('react').ForwardRefExoticComponent<ChipProps & import('react').RefAttributes<HTMLSpanElement>>;
+/**
+ * Chip — mirrors `@sesame/orxata-core` Chip.
+ * `asChild` renders the child element instead of a `<button>`, via
+ * `@radix-ui/react-slot`. It is what the Vue side spells `as` / `as-child`.
+ */
+export declare const Chip: import('react').ForwardRefExoticComponent<ChipProps & import('react').RefAttributes<HTMLButtonElement>>;

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

@@ -2,18 +2,27 @@ import { VariantProps } from 'class-variance-authority';
 export { Chip } from './Chip.tsx';
 export type { ChipProps } from './Chip.tsx';
 /**
- * A chip is a piece of the user's own data — a value they picked, a label they
- * applied. `Badge` is the system talking back: a status it assigned, a count it
- * worked out. That is the line between the two, and it is why one is a soft
- * tint and the other a solid fill.
+ * A chip is a value the user picked — one they can drop, a filter they can
+ * press. `Badge` is the system talking back: a status it assigned, a count it
+ * worked out. That is the line between them, and it is why this one is outlined
+ * and that one a solid fill.
  *
- * The tints are opacity over the semantic colour rather than a `-100` step,
- * because no such token exists for `warning` or `destructive` and inventing one
- * would put a colour in the theme that Figma has never seen. `Table` already
- * tints this way. The pair also cannot drift: background and text come off the
- * same token, so re-pointing `--success` moves both.
+ * It renders a `<button>` by default because pressing one is the common case,
+ * but that is a default and not the component: `asChild` renders it as anything,
+ * and a chip that only shows a value should be a `<span>` rather than a control
+ * with nothing behind it.
+ *
+ * Class names, not utilities: the declarations live in `Chip.module.css` behind
+ * `@apply`. See `Button/index.ts` for the full reasoning.
+ *
+ * The two axes are the design's own, with one renaming. Its `Form` is `shape`
+ * here because `form` on a `<button>` is a native attribute that associates the
+ * button with a form, and a prop of that name would quietly eat it. Its
+ * `Circle` is this `rounded`: an icon chip's box is already square, so the
+ * circle is the same radius as a text chip's pill and needs no value of its own.
  */
 export declare const chipVariants: (props?: ({
-    tone?: "success" | "warning" | "neutral" | "brand" | "error" | null | undefined;
+    size?: "sm" | "lg" | "icon-sm" | "icon-lg" | null | undefined;
+    shape?: "square" | "rounded" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 export type ChipVariants = VariantProps<typeof chipVariants>;

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

@@ -0,0 +1,16 @@
+export interface LoaderProps extends React.HTMLAttributes<HTMLSpanElement> {
+    dataTestid: string;
+}
+/**
+ * The Sesame mark drawing itself, ported from the `HR-loading` After Effects
+ * composition the product ships as a Lottie.
+ *
+ * Nothing in that composition moves: all twelve layers have a static transform
+ * and the whole animation lives in trim paths, which is `stroke-dasharray` plus
+ * `stroke-dashoffset` under another name. So the port needs no player — the
+ * twelve layers collapse to two shapes drawn twice, and the trims become the
+ * `@keyframes` in the stylesheet. That is the reason there is no `lottie-web`
+ * here: 250 KB on every consumer to replay an animation the stylesheet can
+ * express itself.
+ */
+export declare const Loader: import('react').ForwardRefExoticComponent<LoaderProps & import('react').RefAttributes<HTMLSpanElement>>;

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

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

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

@@ -3,5 +3,4 @@ export interface PopoverContentProps extends React.ComponentPropsWithoutRef<type
     showArrow?: boolean;
     dataTestid: string;
 }
-/** PopoverContent — portalled Radix popover content with optional arrow. */
 export declare const PopoverContent: import('react').ForwardRefExoticComponent<PopoverContentProps & import('react').RefAttributes<HTMLDivElement>>;

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

@@ -1,7 +1,10 @@
+import { ProgressVariants } from './index.ts';
 import * as ProgressPrimitive from '@radix-ui/react-progress';
 export interface ProgressProps extends Omit<React.ComponentPropsWithoutRef<typeof ProgressPrimitive.Root>, 'value'> {
     /** How far along, 0 to 100 */
     value?: number;
+    /** What the bar is saying: still going, done, done with a caveat, or failed */
+    variant?: ProgressVariants['variant'];
     dataTestid: string;
 }
 /** Progress — mirrors `@sesame/orxata-core` Progress. */

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

@@ -1,2 +1,19 @@
+import { VariantProps } from 'class-variance-authority';
 export { Progress } from './Progress.tsx';
 export type { ProgressProps } from './Progress.tsx';
+/**
+ * What the bar is saying, not how far along it is.
+ *
+ * `brand` is a bar still filling. The other three are a bar that has stopped
+ * and has something to report: a job that finished, one that finished with
+ * something to look at, one that failed. They are the same three the rest of
+ * the system uses for that, and they read the same here.
+ *
+ * A determinate bar at 100% is not automatically `success` — an upload that
+ * reached the end and then failed to process is at 100% and is not good news.
+ * The variant is the caller's to say.
+ */
+export declare const progressVariants: (props?: ({
+    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/Feedback/Tooltip/TooltipContent.d.ts

@@ -3,5 +3,4 @@ export interface TooltipContentProps extends React.ComponentPropsWithoutRef<type
     showArrow?: boolean;
     dataTestid: string;
 }
-/** TooltipContent — portalled Radix tooltip content with optional arrow. */
 export declare const TooltipContent: import('react').ForwardRefExoticComponent<TooltipContentProps & import('react').RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,9 @@
+export interface CounterProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** How much the field holds now */
+    value: number;
+    /** How much it is allowed to hold */
+    max: number;
+    dataTestid: string;
+}
+/** Counter — mirrors `@sesame/orxata-core` Counter. */
+export declare const Counter: import('react').ForwardRefExoticComponent<CounterProps & import('react').RefAttributes<HTMLSpanElement>>;

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

@@ -0,0 +1,13 @@
+import { VariantProps } from 'class-variance-authority';
+export { Counter, type CounterProps } from './Counter.tsx';
+/**
+ * Whether the field is still within its limit.
+ *
+ * Not a prop: the component has `value` and `max`, so asking a caller to also
+ * tell it which state that adds up to invites the two to disagree — a red
+ * counter reading 20/100, or a grey one reading 150/100.
+ */
+export declare const counterVariants: (props?: ({
+    state?: "over" | "within" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export type CounterVariants = VariantProps<typeof counterVariants>;

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 {};