@birdycom/omniaui-react 0.11.0 → 0.11.1

package/src/components/EmptyState.tsx

@@ -1,27 +1,27 @@
-import { forwardRef } from "react";
-import type { HTMLAttributes, ReactNode } from "react";
-import { cx } from "../utils";
-
-export interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
-  icon?: ReactNode;
-  title: ReactNode;
-  /** Explanation (`oc-empty-text`). */
-  description?: ReactNode;
-  /** Buttons row (`oc-empty-actions`). */
-  actions?: ReactNode;
-}
-
-/** `<div class="oc-empty">` for lists without data. */
-export const EmptyState = forwardRef<HTMLDivElement, EmptyStateProps>(function EmptyState(
-  { icon, title, description, actions, className, ...rest },
-  ref,
-) {
-  return (
-    <div ref={ref} className={cx("oc-empty", className)} {...rest}>
-      {icon != null && <span className="oc-empty-icon" aria-hidden="true">{icon}</span>}
-      <h3 className="oc-empty-title">{title}</h3>
-      {description != null && <p className="oc-empty-text">{description}</p>}
-      {actions != null && <div className="oc-empty-actions">{actions}</div>}
-    </div>
-  );
-});
+import { forwardRef } from "react";
+import type { HTMLAttributes, ReactNode } from "react";
+import { cx } from "../utils";
+
+export interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+  icon?: ReactNode;
+  title: ReactNode;
+  /** Explanation (`oc-empty-text`). */
+  description?: ReactNode;
+  /** Buttons row (`oc-empty-actions`). */
+  actions?: ReactNode;
+}
+
+/** `<div class="oc-empty">` for lists without data. */
+export const EmptyState = forwardRef<HTMLDivElement, EmptyStateProps>(function EmptyState(
+  { icon, title, description, actions, className, ...rest },
+  ref,
+) {
+  return (
+    <div ref={ref} className={cx("oc-empty", className)} {...rest}>
+      {icon != null && <span className="oc-empty-icon" aria-hidden="true">{icon}</span>}
+      <h3 className="oc-empty-title">{title}</h3>
+      {description != null && <p className="oc-empty-text">{description}</p>}
+      {actions != null && <div className="oc-empty-actions">{actions}</div>}
+    </div>
+  );
+});

package/src/components/EntityCard.tsx

@@ -1,56 +1,56 @@
-// File: packages/react/src/components/EntityCard.tsx
-// Map: props -> EntityCard (grid: frame (img / glyph / media) | body (eyebrow, title, description, facts, children) -> footer)
-// Same markup as packages/ui/snippets/entity-card.html.
-import { Fragment, forwardRef } from "react";
-import type { HTMLAttributes, ReactNode } from "react";
-import { cx } from "../utils";
-
-export interface EntityCardProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
-  title: ReactNode;
-  eyebrow?: ReactNode;
-  description?: ReactNode;
-  /** Picture in the frame. */
-  src?: string;
-  alt?: string;
-  /** Large character or icon in the frame (when there is no `src`). */
-  glyph?: ReactNode;
-  /** Anything else for the frame (svg, placeholder art). Wins over src / glyph. */
-  media?: ReactNode;
-  /** Keep a margin around a logo / symbol picture (`__frame--contain`). */
-  contain?: boolean;
-  /** Key / value facts, rendered as a <dl>. */
-  facts?: Array<[ReactNode, ReactNode]>;
-  /** Tags or actions under a divider. */
-  footer?: ReactNode;
-  stacked?: boolean;
-  size?: "sm" | "md";
-}
-
-/** `article.oc-entity-card`: framed media cell + detail column. */
-export const EntityCard = forwardRef<HTMLElement, EntityCardProps>(function EntityCard(
-  { title, eyebrow, description, src, alt = "", glyph, media, contain, facts, footer, stacked, size = "md", className, children, ...rest },
-  ref,
-) {
-  const frame = media ?? (src ? <img src={src} alt={alt} /> : glyph != null ? <span className="oc-entity-card__glyph" aria-hidden="true">{glyph}</span> : null);
-  return (
-    <article ref={ref} className={cx("oc-entity-card", stacked && "oc-entity-card--stacked", size === "sm" && "oc-entity-card--sm", className)} {...rest}>
-      <div className="oc-entity-card__grid">
-        <div className={cx("oc-entity-card__frame", contain && "oc-entity-card__frame--contain")}>{frame}</div>
-        <div className="oc-entity-card__body">
-          {eyebrow != null && <p className="oc-entity-card__eyebrow">{eyebrow}</p>}
-          <h3 className="oc-entity-card__title">{title}</h3>
-          {description != null && <p className="oc-entity-card__description">{description}</p>}
-          {facts && facts.length > 0 && (
-            <dl className="oc-entity-card__facts">
-              {facts.map(([k, v], i) => (
-                <Fragment key={i}><dt>{k}</dt><dd>{v}</dd></Fragment>
-              ))}
-            </dl>
-          )}
-          {children}
-        </div>
-      </div>
-      {footer != null && <div className="oc-entity-card__footer">{footer}</div>}
-    </article>
-  );
-});
+// File: packages/react/src/components/EntityCard.tsx
+// Map: props -> EntityCard (grid: frame (img / glyph / media) | body (eyebrow, title, description, facts, children) -> footer)
+// Same markup as packages/ui/snippets/entity-card.html.
+import { Fragment, forwardRef } from "react";
+import type { HTMLAttributes, ReactNode } from "react";
+import { cx } from "../utils";
+
+export interface EntityCardProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+  title: ReactNode;
+  eyebrow?: ReactNode;
+  description?: ReactNode;
+  /** Picture in the frame. */
+  src?: string;
+  alt?: string;
+  /** Large character or icon in the frame (when there is no `src`). */
+  glyph?: ReactNode;
+  /** Anything else for the frame (svg, placeholder art). Wins over src / glyph. */
+  media?: ReactNode;
+  /** Keep a margin around a logo / symbol picture (`__frame--contain`). */
+  contain?: boolean;
+  /** Key / value facts, rendered as a <dl>. */
+  facts?: Array<[ReactNode, ReactNode]>;
+  /** Tags or actions under a divider. */
+  footer?: ReactNode;
+  stacked?: boolean;
+  size?: "sm" | "md";
+}
+
+/** `article.oc-entity-card`: framed media cell + detail column. */
+export const EntityCard = forwardRef<HTMLElement, EntityCardProps>(function EntityCard(
+  { title, eyebrow, description, src, alt = "", glyph, media, contain, facts, footer, stacked, size = "md", className, children, ...rest },
+  ref,
+) {
+  const frame = media ?? (src ? <img src={src} alt={alt} /> : glyph != null ? <span className="oc-entity-card__glyph" aria-hidden="true">{glyph}</span> : null);
+  return (
+    <article ref={ref} className={cx("oc-entity-card", stacked && "oc-entity-card--stacked", size === "sm" && "oc-entity-card--sm", className)} {...rest}>
+      <div className="oc-entity-card__grid">
+        <div className={cx("oc-entity-card__frame", contain && "oc-entity-card__frame--contain")}>{frame}</div>
+        <div className="oc-entity-card__body">
+          {eyebrow != null && <p className="oc-entity-card__eyebrow">{eyebrow}</p>}
+          <h3 className="oc-entity-card__title">{title}</h3>
+          {description != null && <p className="oc-entity-card__description">{description}</p>}
+          {facts && facts.length > 0 && (
+            <dl className="oc-entity-card__facts">
+              {facts.map(([k, v], i) => (
+                <Fragment key={i}><dt>{k}</dt><dd>{v}</dd></Fragment>
+              ))}
+            </dl>
+          )}
+          {children}
+        </div>
+      </div>
+      {footer != null && <div className="oc-entity-card__footer">{footer}</div>}
+    </article>
+  );
+});

package/src/components/FactList.tsx

@@ -1,43 +1,43 @@
-// File: packages/react/src/components/FactList.tsx | Map: types -> FactList (dl.oc-fact-list -> div > dt + dd)
-import { forwardRef } from "react";
-import type { HTMLAttributes, ReactNode } from "react";
-import { cx } from "../utils";
-
-export interface FactListRow {
-  label: ReactNode;
-  value: ReactNode;
-}
-
-export interface FactListProps extends HTMLAttributes<HTMLDListElement> {
-  items: FactListRow[];
-  plain?: boolean;
-  compact?: boolean;
-  stacked?: boolean;
-  /** Values in the accent color. */
-  accent?: boolean;
-}
-
-/** `<dl class="oc-fact-list">`: key / value product facts (variant of the definition list). */
-export const FactList = forwardRef<HTMLDListElement, FactListProps>(function FactList(
-  { items, plain = false, compact = false, stacked = false, accent = false, className, ...rest },
-  ref,
-) {
-  const classes = cx(
-    "oc-fact-list",
-    plain && "oc-fact-list--plain",
-    compact && "oc-fact-list--compact",
-    stacked && "oc-fact-list--stacked",
-    accent && "oc-fact-list--accent",
-    className,
-  );
-  return (
-    <dl ref={ref} className={classes} {...rest}>
-      {items.map((row, i) => (
-        <div key={i}>
-          <dt>{row.label}</dt>
-          <dd>{row.value}</dd>
-        </div>
-      ))}
-    </dl>
-  );
-});
+// File: packages/react/src/components/FactList.tsx | Map: types -> FactList (dl.oc-fact-list -> div > dt + dd)
+import { forwardRef } from "react";
+import type { HTMLAttributes, ReactNode } from "react";
+import { cx } from "../utils";
+
+export interface FactListRow {
+  label: ReactNode;
+  value: ReactNode;
+}
+
+export interface FactListProps extends HTMLAttributes<HTMLDListElement> {
+  items: FactListRow[];
+  plain?: boolean;
+  compact?: boolean;
+  stacked?: boolean;
+  /** Values in the accent color. */
+  accent?: boolean;
+}
+
+/** `<dl class="oc-fact-list">`: key / value product facts (variant of the definition list). */
+export const FactList = forwardRef<HTMLDListElement, FactListProps>(function FactList(
+  { items, plain = false, compact = false, stacked = false, accent = false, className, ...rest },
+  ref,
+) {
+  const classes = cx(
+    "oc-fact-list",
+    plain && "oc-fact-list--plain",
+    compact && "oc-fact-list--compact",
+    stacked && "oc-fact-list--stacked",
+    accent && "oc-fact-list--accent",
+    className,
+  );
+  return (
+    <dl ref={ref} className={classes} {...rest}>
+      {items.map((row, i) => (
+        <div key={i}>
+          <dt>{row.label}</dt>
+          <dd>{row.value}</dd>
+        </div>
+      ))}
+    </dl>
+  );
+});

package/src/components/FilterCounts.tsx

@@ -1,50 +1,50 @@
-// File: packages/react/src/components/FilterCounts.tsx
-// Map: types -> component (fieldset radiogroup -> one tile per view: radio + value + label + hint)
-// Same markup as packages/ui/snippets/filter-counts.html.
-"use client";
-
-import { forwardRef, useId } from "react";
-import type { FieldsetHTMLAttributes, ReactNode } from "react";
-import { cx } from "../utils";
-import { useControllable } from "../hooks";
-
-export interface FilterCountsOption {
-  value: string;
-  label: ReactNode;
-  count: number | string;
-  hint?: ReactNode;
-  /** Accent color of the tile; default primary. */
-  tone?: "primary" | "success" | "destructive" | "muted";
-  disabled?: boolean;
-}
-
-export interface FilterCountsProps extends Omit<FieldsetHTMLAttributes<HTMLFieldSetElement>, "onChange" | "defaultValue"> {
-  options: FilterCountsOption[];
-  value?: string;
-  defaultValue?: string;
-  onChange?: (value: string) => void;
-  name?: string;
-  /** Small inline pills instead of tiles. */
-  compact?: boolean;
-}
-
-/** `.oc-filter-counts`: choose a view; every tile shows its item count. */
-export const FilterCounts = forwardRef<HTMLFieldSetElement, FilterCountsProps>(function FilterCounts(
-  { options, value, defaultValue, onChange, name, compact, className, ...rest },
-  ref,
-) {
-  const group = name ?? `oc-filter-${useId().replace(/:/g, "")}`;
-  const [current, setCurrent] = useControllable<string>(value, defaultValue ?? options[0]?.value ?? "", onChange);
-  return (
-    <fieldset ref={ref} className={cx("oc-filter-counts", compact && "oc-filter-counts--compact", className)} role="radiogroup" {...rest}>
-      {options.map((o) => (
-        <label key={o.value} className={cx("oc-filter-counts-item", o.tone && o.tone !== "primary" && `oc-filter-counts-item--${o.tone}`)}>
-          <input type="radio" name={group} value={o.value} disabled={o.disabled} checked={current === o.value} onChange={() => setCurrent(o.value)} />
-          <span className="oc-filter-counts-value">{o.count}</span>
-          <span className="oc-filter-counts-label">{o.label}</span>
-          {o.hint != null && <span className="oc-filter-counts-hint">{o.hint}</span>}
-        </label>
-      ))}
-    </fieldset>
-  );
-});
+// File: packages/react/src/components/FilterCounts.tsx
+// Map: types -> component (fieldset radiogroup -> one tile per view: radio + value + label + hint)
+// Same markup as packages/ui/snippets/filter-counts.html.
+"use client";
+
+import { forwardRef, useId } from "react";
+import type { FieldsetHTMLAttributes, ReactNode } from "react";
+import { cx } from "../utils";
+import { useControllable } from "../hooks";
+
+export interface FilterCountsOption {
+  value: string;
+  label: ReactNode;
+  count: number | string;
+  hint?: ReactNode;
+  /** Accent color of the tile; default primary. */
+  tone?: "primary" | "success" | "destructive" | "muted";
+  disabled?: boolean;
+}
+
+export interface FilterCountsProps extends Omit<FieldsetHTMLAttributes<HTMLFieldSetElement>, "onChange" | "defaultValue"> {
+  options: FilterCountsOption[];
+  value?: string;
+  defaultValue?: string;
+  onChange?: (value: string) => void;
+  name?: string;
+  /** Small inline pills instead of tiles. */
+  compact?: boolean;
+}
+
+/** `.oc-filter-counts`: choose a view; every tile shows its item count. */
+export const FilterCounts = forwardRef<HTMLFieldSetElement, FilterCountsProps>(function FilterCounts(
+  { options, value, defaultValue, onChange, name, compact, className, ...rest },
+  ref,
+) {
+  const group = name ?? `oc-filter-${useId().replace(/:/g, "")}`;
+  const [current, setCurrent] = useControllable<string>(value, defaultValue ?? options[0]?.value ?? "", onChange);
+  return (
+    <fieldset ref={ref} className={cx("oc-filter-counts", compact && "oc-filter-counts--compact", className)} role="radiogroup" {...rest}>
+      {options.map((o) => (
+        <label key={o.value} className={cx("oc-filter-counts-item", o.tone && o.tone !== "primary" && `oc-filter-counts-item--${o.tone}`)}>
+          <input type="radio" name={group} value={o.value} disabled={o.disabled} checked={current === o.value} onChange={() => setCurrent(o.value)} />
+          <span className="oc-filter-counts-value">{o.count}</span>
+          <span className="oc-filter-counts-label">{o.label}</span>
+          {o.hint != null && <span className="oc-filter-counts-hint">{o.hint}</span>}
+        </label>
+      ))}
+    </fieldset>
+  );
+});

package/src/components/FlipCard.tsx

@@ -1,55 +1,55 @@
-// File: packages/react/src/components/FlipCard.tsx
-// Map: props -> FlipCard (optional checkbox -> inner -> front face + flip label -> back face + flip label)
-// Same markup as packages/ui/snippets/flip-card.html. trigger="toggle" uses the CSS checkbox, "hover" the --hover
-// modifier, "manual" only the `flipped` prop (.is-flipped).
-"use client";
-
-import { forwardRef, useId } from "react";
-import type { HTMLAttributes, ReactNode } from "react";
-import { cx } from "../utils";
-import { useControllable } from "../hooks";
-
-export interface FlipCardProps extends HTMLAttributes<HTMLDivElement> {
-  front: ReactNode;
-  back: ReactNode;
-  /** How the card flips. Default "toggle" (click / Space). */
-  trigger?: "toggle" | "hover" | "manual";
-  flipped?: boolean;
-  defaultFlipped?: boolean;
-  onFlippedChange?: (flipped: boolean) => void;
-  /** Turn top over bottom instead of left over right. */
-  vertical?: boolean;
-  /** Text of the flip labels (toggle mode). */
-  frontLabel?: ReactNode;
-  backLabel?: ReactNode;
-}
-
-/** `.oc-flip-card`: front / back card that turns in 3D (cross-fades with reduced motion). */
-export const FlipCard = forwardRef<HTMLDivElement, FlipCardProps>(function FlipCard(
-  { front, back, trigger = "toggle", flipped, defaultFlipped = false, onFlippedChange, vertical, frontLabel = "Show answer", backLabel = "Back", className, ...rest },
-  ref,
-) {
-  const id = `oc-flip-${useId().replace(/:/g, "")}`;
-  const [isFlipped, setFlipped] = useControllable(flipped, defaultFlipped, onFlippedChange);
-  const toggle = trigger === "toggle";
-  return (
-    <div
-      ref={ref}
-      className={cx("oc-flip-card", trigger === "hover" && "oc-flip-card--hover", vertical && "oc-flip-card--vertical", !toggle && isFlipped && "is-flipped", className)}
-      tabIndex={trigger === "hover" ? 0 : undefined}
-      {...rest}
-    >
-      {toggle && <input type="checkbox" className="oc-flip-card__toggle" id={id} checked={isFlipped} onChange={(e) => setFlipped(e.target.checked)} />}
-      <div className="oc-flip-card__inner">
-        <div className="oc-flip-card__face oc-flip-card__face--front">
-          {front}
-          {toggle && <label className="oc-flip-card__flip" htmlFor={id}>{frontLabel}</label>}
-        </div>
-        <div className="oc-flip-card__face oc-flip-card__face--back">
-          {back}
-          {toggle && <label className="oc-flip-card__flip" htmlFor={id}>{backLabel}</label>}
-        </div>
-      </div>
-    </div>
-  );
-});
+// File: packages/react/src/components/FlipCard.tsx
+// Map: props -> FlipCard (optional checkbox -> inner -> front face + flip label -> back face + flip label)
+// Same markup as packages/ui/snippets/flip-card.html. trigger="toggle" uses the CSS checkbox, "hover" the --hover
+// modifier, "manual" only the `flipped` prop (.is-flipped).
+"use client";
+
+import { forwardRef, useId } from "react";
+import type { HTMLAttributes, ReactNode } from "react";
+import { cx } from "../utils";
+import { useControllable } from "../hooks";
+
+export interface FlipCardProps extends HTMLAttributes<HTMLDivElement> {
+  front: ReactNode;
+  back: ReactNode;
+  /** How the card flips. Default "toggle" (click / Space). */
+  trigger?: "toggle" | "hover" | "manual";
+  flipped?: boolean;
+  defaultFlipped?: boolean;
+  onFlippedChange?: (flipped: boolean) => void;
+  /** Turn top over bottom instead of left over right. */
+  vertical?: boolean;
+  /** Text of the flip labels (toggle mode). */
+  frontLabel?: ReactNode;
+  backLabel?: ReactNode;
+}
+
+/** `.oc-flip-card`: front / back card that turns in 3D (cross-fades with reduced motion). */
+export const FlipCard = forwardRef<HTMLDivElement, FlipCardProps>(function FlipCard(
+  { front, back, trigger = "toggle", flipped, defaultFlipped = false, onFlippedChange, vertical, frontLabel = "Show answer", backLabel = "Back", className, ...rest },
+  ref,
+) {
+  const id = `oc-flip-${useId().replace(/:/g, "")}`;
+  const [isFlipped, setFlipped] = useControllable(flipped, defaultFlipped, onFlippedChange);
+  const toggle = trigger === "toggle";
+  return (
+    <div
+      ref={ref}
+      className={cx("oc-flip-card", trigger === "hover" && "oc-flip-card--hover", vertical && "oc-flip-card--vertical", !toggle && isFlipped && "is-flipped", className)}
+      tabIndex={trigger === "hover" ? 0 : undefined}
+      {...rest}
+    >
+      {toggle && <input type="checkbox" className="oc-flip-card__toggle" id={id} checked={isFlipped} onChange={(e) => setFlipped(e.target.checked)} />}
+      <div className="oc-flip-card__inner">
+        <div className="oc-flip-card__face oc-flip-card__face--front">
+          {front}
+          {toggle && <label className="oc-flip-card__flip" htmlFor={id}>{frontLabel}</label>}
+        </div>
+        <div className="oc-flip-card__face oc-flip-card__face--back">
+          {back}
+          {toggle && <label className="oc-flip-card__flip" htmlFor={id}>{backLabel}</label>}
+        </div>
+      </div>
+    </div>
+  );
+});

package/src/components/FormField.tsx

@@ -1,54 +1,54 @@
-import { Children, cloneElement, forwardRef, isValidElement, useId } from "react";
-import type { HTMLAttributes, ReactElement, ReactNode } from "react";
-import { cx } from "../utils";
-
-export interface FormFieldProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
-  label?: ReactNode;
-  description?: ReactNode;
-  /** Error message (`oc-field-error`); also sets `aria-invalid` on the control. */
-  error?: ReactNode;
-  /** Horizontal layout (`oc-field--horizontal`). */
-  horizontal?: boolean;
-  /** Id of the control; generated when omitted. */
-  htmlFor?: string;
-  /** A single control (Input, Select, Textarea...) gets id / aria-describedby / aria-invalid injected. */
-  children?: ReactNode;
-}
-
-/** `<div class="oc-field">` with label, control, description and error wired through ids. */
-export const FormField = forwardRef<HTMLDivElement, FormFieldProps>(function FormField(
-  { label, description, error, horizontal, htmlFor, className, children, ...rest },
-  ref,
-) {
-  const auto = useId();
-  const only = Children.count(children) === 1 && isValidElement(children) ? (children as ReactElement<Record<string, unknown>>) : null;
-  const controlId = htmlFor ?? (only?.props.id as string | undefined) ?? `oc-field-${auto.replace(/:/g, "")}`;
-  const helpId = description != null ? `${controlId}-help` : undefined;
-  const errorId = error != null ? `${controlId}-error` : undefined;
-  const describedBy = [only?.props["aria-describedby"] as string | undefined, helpId, errorId].filter(Boolean).join(" ") || undefined;
-
-  const control = only
-    ? cloneElement(only, {
-        id: controlId,
-        "aria-describedby": describedBy,
-        ...(error != null ? { "aria-invalid": true } : {}),
-      })
-    : children;
-
-  return (
-    <div ref={ref} className={cx("oc-field", horizontal && "oc-field--horizontal", className)} {...rest}>
-      {label != null && <label className="oc-field-label" htmlFor={controlId}>{label}</label>}
-      {control}
-      {description != null && <p className="oc-field-description" id={helpId}>{description}</p>}
-      {error != null && <p className="oc-field-error" id={errorId} role="alert">{error}</p>}
-    </div>
-  );
-});
-
-/** `<div class="oc-field-group">`: stack (or `row`) of related controls. */
-export const FieldGroup = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement> & { row?: boolean }>(function FieldGroup(
-  { row, className, ...rest },
-  ref,
-) {
-  return <div ref={ref} className={cx("oc-field-group", row && "oc-field-group--row", className)} {...rest} />;
-});
+import { Children, cloneElement, forwardRef, isValidElement, useId } from "react";
+import type { HTMLAttributes, ReactElement, ReactNode } from "react";
+import { cx } from "../utils";
+
+export interface FormFieldProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+  label?: ReactNode;
+  description?: ReactNode;
+  /** Error message (`oc-field-error`); also sets `aria-invalid` on the control. */
+  error?: ReactNode;
+  /** Horizontal layout (`oc-field--horizontal`). */
+  horizontal?: boolean;
+  /** Id of the control; generated when omitted. */
+  htmlFor?: string;
+  /** A single control (Input, Select, Textarea...) gets id / aria-describedby / aria-invalid injected. */
+  children?: ReactNode;
+}
+
+/** `<div class="oc-field">` with label, control, description and error wired through ids. */
+export const FormField = forwardRef<HTMLDivElement, FormFieldProps>(function FormField(
+  { label, description, error, horizontal, htmlFor, className, children, ...rest },
+  ref,
+) {
+  const auto = useId();
+  const only = Children.count(children) === 1 && isValidElement(children) ? (children as ReactElement<Record<string, unknown>>) : null;
+  const controlId = htmlFor ?? (only?.props.id as string | undefined) ?? `oc-field-${auto.replace(/:/g, "")}`;
+  const helpId = description != null ? `${controlId}-help` : undefined;
+  const errorId = error != null ? `${controlId}-error` : undefined;
+  const describedBy = [only?.props["aria-describedby"] as string | undefined, helpId, errorId].filter(Boolean).join(" ") || undefined;
+
+  const control = only
+    ? cloneElement(only, {
+        id: controlId,
+        "aria-describedby": describedBy,
+        ...(error != null ? { "aria-invalid": true } : {}),
+      })
+    : children;
+
+  return (
+    <div ref={ref} className={cx("oc-field", horizontal && "oc-field--horizontal", className)} {...rest}>
+      {label != null && <label className="oc-field-label" htmlFor={controlId}>{label}</label>}
+      {control}
+      {description != null && <p className="oc-field-description" id={helpId}>{description}</p>}
+      {error != null && <p className="oc-field-error" id={errorId} role="alert">{error}</p>}
+    </div>
+  );
+});
+
+/** `<div class="oc-field-group">`: stack (or `row`) of related controls. */
+export const FieldGroup = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement> & { row?: boolean }>(function FieldGroup(
+  { row, className, ...rest },
+  ref,
+) {
+  return <div ref={ref} className={cx("oc-field-group", row && "oc-field-group--row", className)} {...rest} />;
+});