@birdycom/omniaui-react 0.0.0-stage → 0.11.0

package/src/components/DocViewer.tsx

@@ -0,0 +1,110 @@
+// File: packages/react/src/components/DocViewer.tsx
+// Map: types + demo items -> media (iframe / video / img / placeholder art) -> DocViewer (grid of cards -> one <dialog> per card)
+// Same markup as packages/ui/snippets/doc-viewer.html. No JavaScript: the buttons open the full-screen dialog with
+// invoker commands (command="show-modal" commandfor), closedby="any" closes it on Esc or a click on the backdrop.
+import { forwardRef, useId } from "react";
+import type { HTMLAttributes, ReactNode } from "react";
+import { attrs, cx } from "../utils";
+
+export interface DocViewerItem {
+  /** Name in the bar and the dialog title; also used in the aria-labels. */
+  label: string;
+  /** Small text next to the label, e.g. "PDF · 2.4 MB" or "1:42". */
+  meta?: ReactNode;
+  /** File URL. Leave empty to show placeholder art (`.oc-media-art`). */
+  src?: string;
+  /** Default "pdf" (A4 frame). "video" = 16/9 dark frame, "image" = natural height. */
+  type?: "pdf" | "video" | "image";
+  /** Dialog id (generated when empty). */
+  id?: string;
+  /** Text for the inline preview (aria-label / alt / iframe title). Defaults to the label. */
+  alt?: string;
+  /** Placeholder art variant (`oc-media-art--N`) when there is no src. */
+  art?: number;
+  /** Download link in the dialog bar. */
+  download?: string;
+  /** Where the preview opens: "bar" (expand button) or "frame" (the whole preview). Default: "frame" for video. */
+  open?: "bar" | "frame";
+  /** Set false for a plain card without full-screen dialog. Default true. */
+  fullscreen?: boolean;
+}
+
+export interface DocViewerProps extends HTMLAttributes<HTMLDivElement> {
+  items?: DocViewerItem[];
+  /** Text of the frame button (default "Click for full screen"). */
+  openText?: ReactNode;
+  downloadText?: ReactNode;
+  /** Prefix for generated dialog ids. */
+  idPrefix?: string;
+}
+
+const DEMO: DocViewerItem[] = [
+  { label: "Brochure 2026", meta: "PDF · 2.4 MB", alt: "First page of Brochure 2026", art: 2, download: "#brochure.pdf" },
+  { label: "Site visit", meta: "1:42", type: "video", alt: "Video still: site visit", art: 5 },
+];
+
+const media = (doc: DocViewerItem, alt: string) => {
+  const type = doc.type ?? "pdf";
+  if (!doc.src) return <div className={cx("oc-media-art", doc.art != null && `oc-media-art--${doc.art}`)} role="img" aria-label={alt} />;
+  if (type === "video") return <video src={doc.src} controls preload="metadata" aria-label={alt} />;
+  if (type === "image") return <img src={doc.src} alt={alt} />;
+  return <iframe src={`${doc.src}#toolbar=0&view=FitH`} title={alt} loading="lazy" />;
+};
+
+/** `.oc-doc-viewer-grid` of `figure.oc-doc-viewer` cards, each with its `dialog.oc-doc-viewer-dialog`. */
+export const DocViewer = forwardRef<HTMLDivElement, DocViewerProps>(function DocViewer(
+  { items = DEMO, openText = "Click for full screen", downloadText = "Download", idPrefix, className, ...rest },
+  ref,
+) {
+  const auto = useId().replace(/[^\w-]/g, "");
+  const base = idPrefix ?? `oc-doc-viewer-${auto}`;
+  const idOf = (doc: DocViewerItem, i: number) => doc.id ?? `${base}-${i + 1}`;
+
+  const cards = items.map((doc, i) => {
+    const id = idOf(doc, i);
+    const full = doc.fullscreen !== false;
+    const frame = full && (doc.open ?? (doc.type === "video" ? "frame" : "bar")) === "frame";
+    return (
+      <figure key={i} className={cx("oc-doc-viewer", doc.type === "video" && "oc-doc-viewer--video", doc.type === "image" && "oc-doc-viewer--image")}>
+        <figcaption className="oc-doc-viewer__bar">
+          <span className="oc-doc-viewer__label">{doc.label}</span>
+          {doc.meta != null && <span className="oc-doc-viewer__meta">{doc.meta}</span>}
+          {full && !frame && (
+            <button type="button" className="oc-doc-viewer__expand" {...attrs({ command: "show-modal", commandfor: id })} aria-label={`Open ${doc.label} full screen`}>&#10530;</button>
+          )}
+        </figcaption>
+        <div className="oc-doc-viewer__frame">
+          {media(doc, doc.alt ?? doc.label)}
+          {frame && <button type="button" className="oc-doc-viewer__open" {...attrs({ command: "show-modal", commandfor: id })}>{openText}</button>}
+        </div>
+      </figure>
+    );
+  });
+
+  const dialogs = items.map((doc, i) => {
+    if (doc.fullscreen === false) return null;
+    const id = idOf(doc, i);
+    const close = <button type="button" className="oc-doc-viewer-dialog__close" {...attrs({ command: "close", commandfor: id })} aria-label="Close">&#10005;</button>;
+    return (
+      <dialog key={i} className={cx("oc-doc-viewer-dialog", doc.type === "video" && "oc-doc-viewer-dialog--video")} id={id} {...attrs({ closedby: "any" })} aria-labelledby={`${id}-title`}>
+        <div className="oc-doc-viewer-dialog__bar">
+          <h2 className="oc-doc-viewer-dialog__title" id={`${id}-title`}>{doc.label}</h2>
+          {doc.download ? (
+            <div className="oc-doc-viewer-dialog__actions">
+              <a className="oc-btn oc-btn--outline oc-btn--sm" href={doc.download} download>{downloadText}</a>
+              {close}
+            </div>
+          ) : close}
+        </div>
+        <div className="oc-doc-viewer-dialog__body">{media(doc, doc.type === "video" ? `${doc.label} video` : doc.label)}</div>
+      </dialog>
+    );
+  });
+
+  return (
+    <>
+      <div ref={ref} className={cx("oc-doc-viewer-grid", className)} {...rest}>{cards}</div>
+      {dialogs}
+    </>
+  );
+});

package/src/components/Dropdown.tsx

@@ -0,0 +1,52 @@
+import { forwardRef, useId } from "react";
+import type { AnchorHTMLAttributes, ButtonHTMLAttributes, HTMLAttributes, ReactNode } from "react";
+import { attrs, cx } from "../utils";
+import { Button } from "./Button";
+import type { ButtonProps } from "./Button";
+
+export interface DropdownProps extends HTMLAttributes<HTMLDivElement> {
+  /** Content of the trigger button. */
+  trigger: ReactNode;
+  /** Props for the trigger button (default variant `outline`). */
+  triggerProps?: ButtonProps;
+}
+
+/**
+ * Trigger button + `<div class="oc-dropdown-menu" popover>`, wired with `popovertarget`
+ * (native popover and anchor positioning, no state needed).
+ */
+export const Dropdown = forwardRef<HTMLDivElement, DropdownProps>(function Dropdown(
+  { trigger, triggerProps, className, id, children, ...rest },
+  ref,
+) {
+  const auto = useId();
+  const menuId = id ?? `oc-menu-${auto.replace(/:/g, "")}`;
+  return (
+    <>
+      <Button variant="outline" {...triggerProps} {...attrs({ popovertarget: menuId })}>{trigger}</Button>
+      <div ref={ref} className={cx("oc-dropdown-menu", className)} id={menuId} {...attrs({ popover: "" })} {...rest}>
+        {children}
+      </div>
+    </>
+  );
+});
+
+/** `.oc-dropdown-label` */
+export function DropdownLabel({ className, ...rest }: HTMLAttributes<HTMLDivElement>) {
+  return <div className={cx("oc-dropdown-label", className)} {...rest} />;
+}
+
+/** `.oc-dropdown-separator` */
+export function DropdownSeparator({ className, ...rest }: HTMLAttributes<HTMLDivElement>) {
+  return <div className={cx("oc-dropdown-separator", className)} {...rest} />;
+}
+
+type ItemProps = (AnchorHTMLAttributes<HTMLAnchorElement> & { href: string }) | (ButtonHTMLAttributes<HTMLButtonElement> & { href?: undefined });
+
+/** `.oc-dropdown-item`: an anchor when `href` is set, otherwise a button. */
+export function DropdownItem({ className, ...props }: ItemProps) {
+  if (props.href !== undefined) {
+    return <a className={cx("oc-dropdown-item", className)} {...(props as AnchorHTMLAttributes<HTMLAnchorElement>)} />;
+  }
+  return <button type="button" className={cx("oc-dropdown-item", className)} {...(props as ButtonHTMLAttributes<HTMLButtonElement>)} />;
+}

package/src/components/Dropzone.tsx

@@ -0,0 +1,46 @@
+"use client";
+
+import { forwardRef, useState } from "react";
+import type { DragEvent, InputHTMLAttributes, ReactNode } from "react";
+import { cx } from "../utils";
+
+export interface DropzoneProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "onChange" | "children"> {
+  /** Icon in `oc-dropzone-icon` (inline SVG or glyph). */
+  icon?: ReactNode;
+  /** Main text, e.g. `<strong>Drop invoices here</strong> or click to choose`. */
+  children?: ReactNode;
+  /** Small hint (`oc-dropzone-hint`), e.g. accepted types and size. */
+  hint?: ReactNode;
+  /** Called with the chosen or dropped files. */
+  onFiles?: (files: File[]) => void;
+}
+
+/** `<label class="oc-dropzone">` around a real file input; `is-dragover` while dragging. */
+export const Dropzone = forwardRef<HTMLInputElement, DropzoneProps>(function Dropzone(
+  { icon, children, hint, onFiles, className, ...rest },
+  ref,
+) {
+  const [over, setOver] = useState(false);
+  const stop = (e: DragEvent) => {
+    e.preventDefault();
+    setOver(e.type === "dragover" || e.type === "dragenter");
+  };
+  return (
+    <label
+      className={cx("oc-dropzone", over && "is-dragover", className)}
+      onDragEnter={stop}
+      onDragOver={stop}
+      onDragLeave={stop}
+      onDrop={(e) => {
+        stop(e);
+        const files = Array.from(e.dataTransfer?.files ?? []);
+        if (files.length && !rest.disabled) onFiles?.(files);
+      }}
+    >
+      <input ref={ref} type="file" onChange={(e) => onFiles?.(Array.from(e.target.files ?? []))} {...rest} />
+      {icon != null && <span className="oc-dropzone-icon" aria-hidden="true">{icon}</span>}
+      <span>{children}</span>
+      {hint != null && <span className="oc-dropzone-hint">{hint}</span>}
+    </label>
+  );
+});

package/src/components/EmojiPicker.tsx

@@ -0,0 +1,72 @@
+// File: packages/react/src/components/EmojiPicker.tsx
+// Map: default groups -> props -> EmojiPicker (trigger button -> popover panel -> groups: label + grid of buttons)
+// Same markup as packages/ui/snippets/emoji-picker.html. React calls onSelect and closes the popover.
+"use client";
+
+import { forwardRef, useId } from "react";
+import type { HTMLAttributes, MouseEvent, ReactNode } from "react";
+import { attrs, cx } from "../utils";
+
+export interface EmojiGroup {
+  label?: string;
+  emojis: string[];
+}
+
+const defaultGroups: EmojiGroup[] = [
+  { label: "Smileys", emojis: ["😀", "😃", "😄", "😁", "😂", "🙂", "😉", "😍", "🤔", "😎", "😢", "😴", "😯", "🥳", "😤", "🤗"] },
+  { label: "Gestures", emojis: ["👍", "👎", "👏", "🙌", "👋", "🙏", "✌️", "💪"] },
+  { label: "Objects", emojis: ["❤️", "⭐", "🔥", "🎉", "✅", "🚀", "💡", "☕"] },
+];
+
+export interface EmojiPickerProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> {
+  groups?: EmojiGroup[];
+  /** Called with the picked emoji. */
+  onSelect?: (emoji: string) => void;
+  /** Always-visible panel without trigger / popover. */
+  inline?: boolean;
+  /** Trigger content (default 🙂) and its accessible name. */
+  trigger?: ReactNode;
+  triggerLabel?: string;
+}
+
+/** `.oc-emoji-picker`: popover grid of emoji buttons, anchored to its trigger. */
+export const EmojiPicker = forwardRef<HTMLDivElement, EmojiPickerProps>(function EmojiPicker(
+  { groups = defaultGroups, onSelect, inline, trigger = "🙂", triggerLabel = "Insert emoji", className, id, "aria-label": label = "Emoji", ...rest },
+  ref,
+) {
+  const auto = useId();
+  const panelId = id ?? `oc-emoji-${auto.replace(/:/g, "")}`;
+  const pick = (e: MouseEvent<HTMLButtonElement>, emoji: string) => {
+    onSelect?.(emoji);
+    (e.currentTarget.closest("[popover]") as (HTMLElement & { hidePopover?: () => void }) | null)?.hidePopover?.();
+  };
+  const panel = (
+    <div
+      ref={ref}
+      id={panelId}
+      className={cx("oc-emoji-picker", inline && "oc-emoji-picker--inline", className)}
+      role={inline ? "group" : undefined}
+      aria-label={label}
+      {...(inline ? {} : attrs({ popover: "" }))}
+      {...rest}
+    >
+      {groups.map((g, gi) => (
+        <div key={gi}>
+          {g.label && <p className="oc-emoji-picker__label">{g.label}</p>}
+          <div className="oc-emoji-picker__grid">
+            {g.emojis.map((emoji) => (
+              <button key={emoji} type="button" className="oc-emoji-picker__item" onClick={(e) => pick(e, emoji)}>{emoji}</button>
+            ))}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+  if (inline) return panel;
+  return (
+    <>
+      <button type="button" className="oc-emoji-picker__trigger" aria-label={triggerLabel} {...attrs({ popovertarget: panelId })}>{trigger}</button>
+      {panel}
+    </>
+  );
+});

package/src/components/EmptyState.tsx

@@ -0,0 +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>
+  );
+});

package/src/components/EntityCard.tsx

@@ -0,0 +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>
+  );
+});

package/src/components/FactList.tsx

@@ -0,0 +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>
+  );
+});

package/src/components/FilterCounts.tsx

@@ -0,0 +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>
+  );
+});

package/src/components/FlipCard.tsx

@@ -0,0 +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>
+  );
+});

package/src/components/FormField.tsx

@@ -0,0 +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} />;
+});

package/src/components/Greeting.tsx

@@ -0,0 +1,63 @@
+// File: packages/react/src/components/Greeting.tsx
+// Map: greetingTimeOfDay() helper -> Greeting = header -> icon -> body (eyebrow, title + name, date) -> actions
+// The time of day is computed from `date` (default: now). Morning 05-12, afternoon 12-18, evening otherwise.
+import { forwardRef } from "react";
+import type { HTMLAttributes, ReactNode } from "react";
+import { cx } from "../utils";
+
+export type GreetingTimeOfDay = "morning" | "afternoon" | "evening";
+
+/** Pick the time-of-day modifier for a date. */
+export function greetingTimeOfDay(date: Date = new Date()): GreetingTimeOfDay {
+  const h = date.getHours();
+  if (h >= 5 && h < 12) return "morning";
+  if (h >= 12 && h < 18) return "afternoon";
+  return "evening";
+}
+
+const WORDS: Record<GreetingTimeOfDay, string> = { morning: "Good morning", afternoon: "Good afternoon", evening: "Good evening" };
+
+export interface GreetingProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+  name?: ReactNode;
+  /** The moment to greet for (default: now). Also shown as the date. */
+  date?: Date;
+  /** Force a time of day instead of computing it. */
+  timeOfDay?: GreetingTimeOfDay;
+  /** Translated greetings, e.g. `{ morning: "Goedemorgen", ... }`. */
+  words?: Partial<Record<GreetingTimeOfDay, string>>;
+  /** Locale for the date text (default: the browser locale). */
+  locale?: string;
+  /** Hide the date line. */
+  hideDate?: boolean;
+  eyebrow?: ReactNode;
+  icon?: ReactNode;
+  actions?: ReactNode;
+  size?: "lg";
+}
+
+/** `.oc-greeting`: dashboard greeting with date and actions. */
+export const Greeting = forwardRef<HTMLElement, GreetingProps>(function Greeting(
+  { name, date, timeOfDay, words, locale, hideDate, eyebrow, icon, actions, size, className, ...rest },
+  ref,
+) {
+  const when = date ?? new Date();
+  const tod = timeOfDay ?? greetingTimeOfDay(when);
+  const word = words?.[tod] ?? WORDS[tod];
+  const dateText = new Intl.DateTimeFormat(locale, { weekday: "long", day: "numeric", month: "long", year: "numeric" }).format(when);
+  // datetime needs YYYY-MM-DD in local time (toISOString would use UTC).
+  const iso = `${when.getFullYear()}-${String(when.getMonth() + 1).padStart(2, "0")}-${String(when.getDate()).padStart(2, "0")}`;
+  return (
+    <header ref={ref} className={cx("oc-greeting", `oc-greeting--${tod}`, size && `oc-greeting--${size}`, className)} {...rest}>
+      {icon != null && <span className="oc-greeting-icon" aria-hidden="true">{icon}</span>}
+      <div className="oc-greeting-body">
+        {eyebrow != null && <p className="oc-greeting-eyebrow">{eyebrow}</p>}
+        <h2 className="oc-greeting-title">
+          {word}
+          {name != null && <>, <span className="oc-greeting-name">{name}</span></>}
+        </h2>
+        {!hideDate && <time className="oc-greeting-date" dateTime={iso}>{dateText}</time>}
+      </div>
+      {actions != null && <div className="oc-greeting-actions">{actions}</div>}
+    </header>
+  );
+});