@marktiderman/genesis-forms-web 0.2.0 → 0.3.0

package/README.md

@@ -24,7 +24,7 @@ import { Form } from "@marktiderman/genesis-forms-web";
   progress bar and Enter to continue (Ctrl/Cmd+Enter in long text; Enter on a focused radio or
   checkbox too). After a single pick (rating, NPS, yes/no, one choice) it moves on by itself
   (`autoAdvance={false}` turns it off): only a click, tap or Space counts as a pick, arrow keys just
-  move through the options, and it never moves on from the last question, so Submit is always a
+  move through the options, and it never moves on from the last question, so Send is always a
   deliberate press. `classic` shows every visible question; a failed submit focuses an error summary
   above the fields that links to each invalid one.
 - **Presentation:** `presentation="embedded"` (the default) is a block inside your own page.
@@ -40,7 +40,7 @@ import { Form } from "@marktiderman/genesis-forms-web";
   button at the top-left. Each new question fades and slides in (CSS `@starting-style`, none with
   `prefers-reduced-motion`). The ending is centred and large. In classic layout, page mode is one
   scrolling page, Google Forms style: a header card with the title and description, each question
-  in its own card (red-edged while invalid), Submit at the end.
+  in its own card (red-edged while invalid), Send at the end.
   `brand={{ name: "Acme", logo }}` shows an organisation's or business's logo (an image URL or an
   element; its initials without one) and name small at the top of every step and on the ending.
   Custom slots and renderers can match with `useFormPresentation()`, which returns
@@ -57,6 +57,18 @@ import { Form } from "@marktiderman/genesis-forms-web";
   question text), a failed Next is announced once through a live region, and the ending heading
   takes focus. Choice rows are full-width labels at least 44px tall; motion respects
   `prefers-reduced-motion`. Ids are unique per form, so two forms can share a page.
+- **Send word and required note:** the send button says `submitLabel` (default **Send**) in every
+  layout. When any question is required, the title shows "\* Required" (`requiredLabel`, default
+  "Required"; `null` hides it).
+- **Theme:** `theme={{ accent: "#f97316", headerImage: url, headerImageAlt }}` sets the form's own
+  primary colour (buttons, selected options, stars, progress, focus rings) and a banner over the
+  title. The accent is adjusted only as far as contrast needs: at least 3:1 against the page in light
+  and dark, and text on it at least 4.5:1. It takes `#rgb`, `#rrggbb` or `rgb()`; anything else is
+  ignored. `themeColors(accent)` returns the colours it would use.
+- **Question types:** besides text, email, phone, rating, NPS, choices and yes/no, there are
+  `dropdown` (a native select), `number` (min, max, step; the decimal keypad on phones), `date` (the
+  browser's date picker) and `consent` (one checkbox). A rating can show end labels (`lowLabel`,
+  `highLabel`) and `display: "stars"`; NPS takes the same labels.
 - **Submitting:** the ending shows once `onSubmit` resolves. If it rejects, the completed response
   stays on screen read-only (a completed response is final), Back is hidden, and "Try again"
   (`retryLabel`) resends the same answers.
@@ -96,6 +108,10 @@ choice, yes/no, and the structured types:
 
 `useMediaTime()` and `useSourceText()` read them in a custom renderer.
 
+A **`calculated`** field shows the value the engine worked out from other answers, read-only, in an
+`<output>` named by the question that announces changes politely. It follows the field's `format`
+and `decimals`, and shows a dash until there is a value.
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -21,10 +21,56 @@ interface FormPresentationValue {
  */
 declare function useFormPresentation(): FormPresentationValue;
 
+/**
+ * A form's own look: an accent colour and a header image. The accent becomes
+ * the Genesis `--primary` (and `--ring`) inside the form, so every primary
+ * surface follows it: buttons, selected options, stars, progress, focus rings.
+ */
+interface FormTheme {
+    /**
+     * The accent colour, as `#rgb`, `#rrggbb` or `rgb(r, g, b)`, such as a
+     * brand's colour. It is adjusted only as far as needed for contrast: at
+     * least 3:1 against the page (light and dark), with text on it at least
+     * 4.5:1 (white or near-black, whichever reads better). Anything else is ignored.
+     */
+    accent?: string | undefined;
+    /** A banner image URL shown over the form's title. */
+    headerImage?: string | undefined;
+    /** The banner's text alternative. Default "" (decorative). */
+    headerImageAlt?: string | undefined;
+}
+/** Shadcn HSL components (`"221 83% 53%"`), as Genesis tokens hold them. */
+interface ThemeColors {
+    primary: string;
+    primaryForeground: string;
+}
+/**
+ * The accent as Genesis primary colours for a light and a dark page, each
+ * adjusted only as far as contrast needs. Null when `accent` is not a colour
+ * this understands.
+ */
+declare function themeColors(accent: string): {
+    light: ThemeColors;
+    dark: ThemeColors;
+} | null;
+/** The CSS that applies `theme` to the elements matching `selector`, or "" when it changes no colour. */
+declare function themeCss(theme: FormTheme | undefined, selector: string): string;
+
 type SlotOverride<P> = ComponentType<P> | null;
 interface HeaderSlotProps {
     title: string;
     description?: string;
+    /** `theme.headerImage`: a banner over the title. */
+    image?: {
+        src: string;
+        alt: string;
+    } | undefined;
+    /**
+     * The note that marks required questions ("Required", drawn as "* Required"),
+     * set when the form has at least one required question. Empty when it has none
+     * or `requiredLabel` is null.
+     */
+    requiredNote?: string | undefined;
     className?: string;
 }
 interface BrandSlotProps {
@@ -112,6 +158,13 @@ interface FormProps {
     presentation?: FormPresentation | undefined;
     /** An organisation's or business's name and logo, shown small at the top of every step and on the ending. */
     brand?: FormBrand | undefined;
+    /**
+     * Colours and a header image: `accent` replaces the primary colour (buttons,
+     * selected options, progress, focus ring), adjusted where needed so it keeps
+     * at least 3:1 contrast with the page and its text 4.5:1; `headerImage` is a
+     * banner over the title.
+     */
+    theme?: FormTheme | undefined;
     registry?: RendererRegistry | undefined;
     /**
      * Called once the form completes. The ending shows only after it resolves.
@@ -130,8 +183,15 @@ interface FormProps {
      * Never moves on from the last question. Default true.
      */
     autoAdvance?: boolean | undefined;
+    /** The send button's word, the same in every layout. Default "Send". */
     submitLabel?: string | undefined;
+    /** The button that moves to the next question in focus layout. Default "OK". */
     nextLabel?: string | undefined;
+    /**
+     * The note shown with the title when any question is required, after an
+     * asterisk ("* Required"). `null` hides it. Default "Required".
+     */
+    requiredLabel?: string | null | undefined;
     /** The submit button's label after `onSubmit` failed. Default "Try again". */
     retryLabel?: string | undefined;
     slots?: {
@@ -198,4 +258,4 @@ declare const SourceTextContext: react.Context<string | null>;
 /** The enclosing `SourceTextContext` value, or null. */
 declare function useSourceText(): string | null;
 
-export { type BrandSlotProps, type EndingSlotProps, type ErrorSummaryItem, type ErrorSummarySlotProps, FieldChrome, type FieldChromeProps, Form, type FormBrand, type FormPresentation, type FormPresentationValue, type FormProps, type FormSlotMap, type HeaderSlotProps, type MediaTime, MediaTimeContext, type NavigationSlotProps, type ProgressSlotProps, SourceTextContext, builtInRenderers, defaultRegistry, describedBy, useFormPresentation, useMediaTime, useSourceText };
+export { type BrandSlotProps, type EndingSlotProps, type ErrorSummaryItem, type ErrorSummarySlotProps, FieldChrome, type FieldChromeProps, Form, type FormBrand, type FormPresentation, type FormPresentationValue, type FormProps, type FormSlotMap, type FormTheme, type HeaderSlotProps, type MediaTime, MediaTimeContext, type NavigationSlotProps, type ProgressSlotProps, SourceTextContext, type ThemeColors, builtInRenderers, defaultRegistry, describedBy, themeColors, themeCss, useFormPresentation, useMediaTime, useSourceText };

package/dist/index.js

@@ -1,5 +1,5 @@
 "use client";
-import { createContext, useRef, useState, useId, useEffect, useContext, useLayoutEffect } from 'react';
+import { createContext, useState, useEffect, useRef, useId, useContext, useLayoutEffect } from 'react';
 import { Button } from '@marktiderman/genesis-ui/button';
 import { Progress } from '@marktiderman/genesis-ui/progress';
 import { cn } from '@marktiderman/genesis-ui/utils';
@@ -9,7 +9,7 @@ import { Input } from '@marktiderman/genesis-ui/input';
 import { Label } from '@marktiderman/genesis-ui/label';
 import { RadioGroup, RadioGroupItem } from '@marktiderman/genesis-ui/radio-group';
 import { Textarea } from '@marktiderman/genesis-ui/textarea';
-import { choiceOptions, listLimits, tableColumns, tableLimits, parseTimestamp, formatTimestamp, getFieldType } from '@marktiderman/genesis-forms';
+import { ratingDisplay, choiceOptions, numberLimits, dateLimits, listLimits, tableColumns, tableLimits, parseTimestamp, formatTimestamp, formatCalculated, getFieldType, scaleLabels } from '@marktiderman/genesis-forms';
 import { FormDescription, FormError, FormLabel } from '@marktiderman/genesis-ui/form-field';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { Stack } from '@marktiderman/genesis-ui/layout';
@@ -120,6 +120,29 @@ function describedBy(props) {
   ].filter(Boolean);
   return ids.length ? ids.join(" ") : void 0;
 }
+function CalculatedField(props) {
+  const { binding, inputId } = props;
+  const { presentation, layout } = useFormPresentation();
+  const pageFocus = presentation === "page" && layout === "focus";
+  const text = formatCalculated(binding.value, binding.field);
+  return /* @__PURE__ */ jsx(FieldChrome, { props, children: /* @__PURE__ */ jsx(
+    "output",
+    {
+      id: inputId,
+      "aria-labelledby": `${inputId}-label`,
+      "aria-describedby": describedBy(props),
+      "aria-live": "polite",
+      "data-gf-calculated": "",
+      className: cn(
+        "block rounded-md border border-dashed bg-muted/40 px-3 py-2 font-medium tabular-nums",
+        pageFocus ? "text-2xl sm:text-3xl" : "text-base",
+        !text && "text-muted-foreground"
+      ),
+      children: text || "\u2014"
+    }
+  ) });
+}
+var calculatedRenderers = [{ type: "calculated", Component: CalculatedField }];
 var MediaTimeContext = createContext(null);
 function useMediaTime() {
   return useContext(MediaTimeContext);
@@ -894,32 +917,88 @@ function scaleValues(type, max) {
   if (type === "nps") return Array.from({ length: 11 }, (_, i) => i);
   return Array.from({ length: max }, (_, i) => i + 1);
 }
+function endLabels(props) {
+  const own = scaleLabels(props.binding.field);
+  if (props.binding.field.type !== "nps") return own;
+  return { low: own.low ?? "Not likely", high: own.high ?? "Very likely" };
+}
+function EndLabels({ inputId, low, high }) {
+  if (!low && !high) return null;
+  return /* @__PURE__ */ jsxs("div", { className: "flex justify-between gap-4 text-sm text-muted-foreground", "data-gf-scale-labels": "", children: [
+    /* @__PURE__ */ jsx("span", { id: `${inputId}-low`, children: low ?? "" }),
+    /* @__PURE__ */ jsx("span", { id: `${inputId}-high`, className: "text-right", children: high ?? "" })
+  ] });
+}
 function ScaleField(props) {
   const { binding, inputId } = props;
   const max = typeof binding.field.props?.max === "number" ? binding.field.props.max : 5;
   const values = scaleValues(binding.field.type, max);
-  const nps = binding.field.type === "nps";
-  const options = values.map((n, i) => ({
-    value: String(n),
-    label: String(n),
-    describedBy: nps && i === 0 ? `${inputId}-low` : nps && i === values.length - 1 ? `${inputId}-high` : void 0
-  }));
+  const { low, high } = endLabels(props);
+  const stars = binding.field.type === "rating" && ratingDisplay(binding.field) === "stars";
+  const describe = (i) => low && i === 0 ? `${inputId}-low` : high && i === values.length - 1 ? `${inputId}-high` : void 0;
+  const value = typeof binding.value === "number" ? String(binding.value) : "";
+  const onValueChange = (v) => binding.setValue(Number(v));
+  if (stars) {
+    return /* @__PURE__ */ jsxs(FieldChrome, { props, children: [
+      /* @__PURE__ */ jsx(StarRadioGroup, { props, values, value, onValueChange, describe }),
+      /* @__PURE__ */ jsx(EndLabels, { inputId, low, high })
+    ] });
+  }
+  const options = values.map((n, i) => ({ value: String(n), label: String(n), describedBy: describe(i) }));
   return /* @__PURE__ */ jsxs(FieldChrome, { props, children: [
-    /* @__PURE__ */ jsx(
-      ButtonRadioGroup,
-      {
-        props,
-        options,
-        value: typeof binding.value === "number" ? String(binding.value) : "",
-        onValueChange: (v) => binding.setValue(Number(v))
-      }
-    ),
-    nps ? /* @__PURE__ */ jsxs("div", { className: "flex justify-between text-sm text-muted-foreground", children: [
-      /* @__PURE__ */ jsx("span", { id: `${inputId}-low`, children: "Not likely" }),
-      /* @__PURE__ */ jsx("span", { id: `${inputId}-high`, children: "Very likely" })
-    ] }) : null
+    /* @__PURE__ */ jsx(ButtonRadioGroup, { props, options, value, onValueChange }),
+    /* @__PURE__ */ jsx(EndLabels, { inputId, low, high })
   ] });
 }
+function StarIcon({ filled }) {
+  return /* @__PURE__ */ jsx(
+    "svg",
+    {
+      viewBox: "0 0 24 24",
+      "aria-hidden": "true",
+      className: cn("size-8 transition-colors motion-reduce:transition-none", filled ? "fill-primary text-primary" : "fill-transparent text-muted-foreground"),
+      stroke: "currentColor",
+      strokeWidth: "1.75",
+      strokeLinejoin: "round",
+      children: /* @__PURE__ */ jsx("path", { d: "M12 2.5l2.9 6.1 6.6.8-4.9 4.6 1.3 6.6L12 17.3l-5.9 3.3 1.3-6.6-4.9-4.6 6.6-.8z" })
+    }
+  );
+}
+function StarRadioGroup({
+  props,
+  values,
+  value,
+  onValueChange,
+  describe
+}) {
+  const pick = useDeliberatePick(props.onAdvance);
+  const chosen = value === "" ? 0 : Number(value);
+  const max = values[values.length - 1] ?? 5;
+  return /* @__PURE__ */ jsx(
+    RadioGroup,
+    {
+      ...groupAria(props),
+      ...pick.rootProps,
+      value,
+      onValueChange,
+      className: "flex flex-wrap justify-start gap-1",
+      "data-gf-stars": "",
+      children: values.map((n, i) => /* @__PURE__ */ jsxs("div", { className: "relative", children: [
+        /* @__PURE__ */ jsx(
+          RadioGroupItem,
+          {
+            value: String(n),
+            "aria-label": `${n} of ${max}`,
+            "aria-describedby": describe(i),
+            onClick: pick.onItemClick,
+            className: "peer size-11 aspect-auto rounded-md border-0 bg-transparent shadow-none hover:bg-accent data-[state=checked]:bg-transparent [&_svg]:hidden"
+          }
+        ),
+        /* @__PURE__ */ jsx("span", { "aria-hidden": "true", className: "pointer-events-none absolute inset-0 flex items-center justify-center peer-disabled:opacity-50", children: /* @__PURE__ */ jsx(StarIcon, { filled: n <= chosen }) })
+      ] }, n))
+    }
+  );
+}
 function YesNoField(props) {
   const { binding } = props;
   const current = binding.value === true ? "yes" : binding.value === false ? "no" : "";
@@ -1049,6 +1128,115 @@ function MultiChoiceField(props) {
     ] }, o.value))
   ] }) });
 }
+function useLineClass() {
+  const { presentation, layout } = useFormPresentation();
+  if (presentation === "page" && layout === "focus") {
+    return "h-auto rounded-none border-0 border-b-2 border-input bg-transparent px-0 py-2 text-xl shadow-none md:text-2xl sm:text-2xl focus-visible:border-primary focus-visible:ring-0 focus-visible:ring-offset-0 aria-invalid:border-destructive";
+  }
+  return presentation === "page" ? "h-11 md:text-base" : void 0;
+}
+function controlAria(props) {
+  return {
+    id: props.inputId,
+    "data-gf-focus": "",
+    "aria-invalid": props.binding.error ? true : void 0,
+    "aria-required": props.binding.field.required || void 0,
+    "aria-describedby": describedBy(props)
+  };
+}
+function DropdownField(props) {
+  const { binding } = props;
+  const options = choiceOptions(binding.field);
+  const line = useLineClass();
+  const value = typeof binding.value === "string" ? binding.value : "";
+  return /* @__PURE__ */ jsx(FieldChrome, { props, children: /* @__PURE__ */ jsxs(
+    "select",
+    {
+      ...controlAria(props),
+      value,
+      onChange: (e) => binding.setValue(e.target.value === "" ? void 0 : e.target.value),
+      className: cn(
+        "flex h-10 w-full min-w-0 rounded-md border border-input bg-background px-3 py-2 text-base ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 md:text-sm aria-invalid:border-destructive",
+        value === "" && "text-muted-foreground",
+        line
+      ),
+      children: [
+        /* @__PURE__ */ jsx("option", { value: "", children: binding.field.placeholder ?? "Choose\u2026" }),
+        options.map((o) => /* @__PURE__ */ jsx("option", { value: o.value, children: o.label ?? o.value }, o.value))
+      ]
+    }
+  ) });
+}
+function NumberField(props) {
+  const { binding } = props;
+  const { min, max, step } = numberLimits(binding.field);
+  const line = useLineClass();
+  const shown = typeof binding.value === "number" ? String(binding.value) : typeof binding.value === "string" ? binding.value : "";
+  const [text, setText] = useState(shown);
+  useEffect(() => {
+    setText((typed) => typed.trim() !== "" && Number(typed.trim().replace(",", ".")) === binding.value ? typed : shown);
+  }, [shown, binding.value]);
+  return /* @__PURE__ */ jsxs(FieldChrome, { props, children: [
+    /* @__PURE__ */ jsx(
+      Input,
+      {
+        ...controlAria(props),
+        type: "text",
+        inputMode: min !== void 0 && min >= 0 && (step === void 0 || Number.isInteger(step)) ? "numeric" : "decimal",
+        autoComplete: "off",
+        value: text,
+        placeholder: binding.field.placeholder,
+        className: line,
+        onChange: (e) => {
+          const raw = e.target.value;
+          setText(raw);
+          const t = raw.trim().replace(",", ".");
+          if (t === "") binding.setValue(void 0);
+          else {
+            const n = Number(t);
+            binding.setValue(Number.isFinite(n) && /^[-+]?(\d+\.?\d*|\.\d+)(e[-+]?\d+)?$/i.test(t) ? n : raw);
+          }
+        }
+      }
+    ),
+    min !== void 0 || max !== void 0 ? /* @__PURE__ */ jsx("p", { className: "text-sm text-muted-foreground", "data-gf-number-range": "", children: min !== void 0 && max !== void 0 ? `From ${min} to ${max}` : min !== void 0 ? `${min} or more` : `${max} or less` }) : null
+  ] });
+}
+function DateField(props) {
+  const { binding } = props;
+  const { min, max } = dateLimits(binding.field);
+  const line = useLineClass();
+  return /* @__PURE__ */ jsx(FieldChrome, { props, children: /* @__PURE__ */ jsx(
+    Input,
+    {
+      ...controlAria(props),
+      type: "date",
+      min,
+      max,
+      value: typeof binding.value === "string" ? binding.value : "",
+      className: cn("w-full sm:w-auto sm:min-w-48", line),
+      onChange: (e) => binding.setValue(e.target.value === "" ? void 0 : e.target.value)
+    }
+  ) });
+}
+function ConsentField(props) {
+  const { binding, inputId } = props;
+  const text = typeof binding.field.props?.text === "string" && binding.field.props.text.trim() ? binding.field.props.text : "I agree";
+  const look = useChoiceLook(inputId, 1);
+  return /* @__PURE__ */ jsx(FieldChrome, { props, children: /* @__PURE__ */ jsxs(Label, { htmlFor: `${inputId}-0`, className: look.row, children: [
+    /* @__PURE__ */ jsx(
+      Checkbox,
+      {
+        id: `${inputId}-0`,
+        checked: binding.value === true,
+        "aria-invalid": binding.error ? true : void 0,
+        "aria-required": binding.field.required || void 0,
+        onCheckedChange: (c) => binding.setValue(c === true ? true : void 0)
+      }
+    ),
+    /* @__PURE__ */ jsx("span", { children: props.engine.text(text) })
+  ] }) });
+}
 var builtInRenderers = [
   { type: "short-text", Component: (p) => /* @__PURE__ */ jsx(TextField, { ...p }) },
   { type: "long-text", Component: (p) => /* @__PURE__ */ jsx(TextField, { ...p, multiline: true }) },
@@ -1061,21 +1249,127 @@ var builtInRenderers = [
   { type: "single-choice", Component: SingleChoiceField },
   { type: "multi-choice", Component: MultiChoiceField },
   { type: "yes-no", Component: YesNoField },
-  ...structuredRenderers
+  { type: "dropdown", Component: DropdownField },
+  { type: "number", Component: NumberField },
+  { type: "date", Component: DateField },
+  { type: "consent", Component: ConsentField },
+  ...structuredRenderers,
+  ...calculatedRenderers
 ];
 var defaultRegistry = createRendererRegistry(builtInRenderers);
+
+// src/theme.ts
+function parseColor(value) {
+  const v = value.trim().toLowerCase();
+  let m = /^#([0-9a-f]{3})$/.exec(v);
+  if (m) return [...m[1]].map((c) => parseInt(c + c, 16));
+  m = /^#([0-9a-f]{6})$/.exec(v);
+  if (m) return [0, 2, 4].map((i) => parseInt(m[1].slice(i, i + 2), 16));
+  m = /^rgb\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*\)$/.exec(v);
+  if (m) {
+    const rgb = [m[1], m[2], m[3]].map(Number);
+    return rgb.every((c) => c <= 255) ? rgb : null;
+  }
+  return null;
+}
+function rgbToHsl([r, g, b]) {
+  const [rn, gn, bn] = [r / 255, g / 255, b / 255];
+  const max = Math.max(rn, gn, bn);
+  const min = Math.min(rn, gn, bn);
+  const l = (max + min) / 2;
+  if (max === min) return [0, 0, l * 100];
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  const h = max === rn ? (gn - bn) / d + (gn < bn ? 6 : 0) : max === gn ? (bn - rn) / d + 2 : (rn - gn) / d + 4;
+  return [h * 60, s * 100, l * 100];
+}
+function hslToRgb(h, s, l) {
+  const sn = s / 100;
+  const ln = l / 100;
+  const k = (n) => (n + h / 30) % 12;
+  const a = sn * Math.min(ln, 1 - ln);
+  const f = (n) => ln - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
+  return [f(0), f(8), f(4)].map((x) => Math.round(x * 255));
+}
+function luminance([r, g, b]) {
+  const c = (x) => {
+    const n = x / 255;
+    return n <= 0.03928 ? n / 12.92 : ((n + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * c(r) + 0.7152 * c(g) + 0.0722 * c(b);
+}
+function contrast(a, b) {
+  const [x, y] = [luminance(a), luminance(b)].sort((p, q) => q - p);
+  return (x + 0.05) / (y + 0.05);
+}
+var WHITE = [255, 255, 255];
+var NEAR_BLACK = hslToRgb(240, 10, 3.9);
+var WHITE_HSL = "0 0% 100%";
+var NEAR_BLACK_HSL = "240 10% 3.9%";
+var fmt = (h, s, l) => `${Math.round(h)} ${Math.round(s)}% ${Math.round(l * 10) / 10}%`;
+function fit(h, s, l, page, darken) {
+  let light = l;
+  for (let i = 0; i < 100 && contrast(hslToRgb(h, s, light), page) < 3; i++) light = Math.max(0, Math.min(100, light + (darken ? -1 : 1)));
+  const best = () => {
+    const rgb = hslToRgb(h, s, light);
+    const white = contrast(rgb, WHITE);
+    const dark = contrast(rgb, NEAR_BLACK);
+    return white >= dark ? { ratio: white, fg: WHITE_HSL } : { ratio: dark, fg: NEAR_BLACK_HSL };
+  };
+  let pick = best();
+  for (let i = 0; i < 100 && pick.ratio < 4.5; i++) {
+    light = Math.min(100, light + 1);
+    pick = { ratio: contrast(hslToRgb(h, s, light), NEAR_BLACK), fg: NEAR_BLACK_HSL };
+  }
+  return { primary: fmt(h, s, light), primaryForeground: pick.fg };
+}
+function themeColors(accent) {
+  const rgb = parseColor(accent);
+  if (!rgb) return null;
+  const [h, s, l] = rgbToHsl(rgb);
+  return { light: fit(h, s, l, WHITE, true), dark: fit(h, s, l, NEAR_BLACK, false) };
+}
+function themeCss(theme, selector) {
+  const colors = theme?.accent ? themeColors(theme.accent) : null;
+  if (!colors) return "";
+  const block = (c) => `--primary: ${c.primary}; --primary-foreground: ${c.primaryForeground}; --ring: ${c.primary};`;
+  return `${selector} { ${block(colors.light)} }
+.dark ${selector}, ${selector}.dark { ${block(colors.dark)} }`;
+}
 function renderSlot(Default, override, props, extra) {
   if (override === null) return null;
   const Component = override ?? Default;
   return /* @__PURE__ */ jsx(Component, { ...props, ...extra });
 }
 var focusRing = "outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 ring-offset-background";
-function DefaultHeader({ title, description, className }) {
+function RequiredNote({ text, className }) {
+  return /* @__PURE__ */ jsxs("p", { className: cn("text-sm text-muted-foreground", className), "data-gf-required-note": "", children: [
+    /* @__PURE__ */ jsxs("span", { className: "text-destructive", "aria-hidden": "true", children: [
+      "*",
+      " "
+    ] }),
+    text
+  ] });
+}
+function HeaderImage({ image, className }) {
+  return /* @__PURE__ */ jsx(
+    "img",
+    {
+      src: image.src,
+      alt: image.alt,
+      "data-gf-header-image": "",
+      className: cn("block h-32 w-full object-cover sm:h-44", className)
+    }
+  );
+}
+function DefaultHeader({ title, description, image, requiredNote, className }) {
   const { presentation, layout } = useFormPresentation();
   if (presentation === "page" && layout === "focus") {
     return /* @__PURE__ */ jsxs("header", { className: cn("space-y-1", className), children: [
+      image ? /* @__PURE__ */ jsx(HeaderImage, { image, className: "mb-4 rounded-lg" }) : null,
       /* @__PURE__ */ jsx("h1", { className: "text-sm font-medium text-muted-foreground", children: title }),
-      description ? /* @__PURE__ */ jsx("p", { className: "text-sm text-muted-foreground", children: description }) : null
+      description ? /* @__PURE__ */ jsx("p", { className: "text-sm text-muted-foreground", children: description }) : null,
+      requiredNote ? /* @__PURE__ */ jsx(RequiredNote, { text: requiredNote }) : null
     ] });
   }
   if (presentation === "page") {
@@ -1083,19 +1377,26 @@ function DefaultHeader({ title, description, className }) {
       "header",
       {
         className: cn(
-          "rounded-xl border border-t-8 border-t-primary bg-card px-5 py-6 text-card-foreground sm:px-8 sm:py-8",
+          "overflow-hidden rounded-xl border bg-card text-card-foreground",
+          !image && "border-t-8 border-t-primary",
           className
         ),
         children: [
-          /* @__PURE__ */ jsx("h1", { className: "text-3xl font-semibold tracking-tight text-balance sm:text-4xl", children: title }),
-          description ? /* @__PURE__ */ jsx("p", { className: "mt-3 text-base text-muted-foreground text-pretty", children: description }) : null
+          image ? /* @__PURE__ */ jsx(HeaderImage, { image }) : null,
+          /* @__PURE__ */ jsxs("div", { className: cn("px-5 py-6 sm:px-8 sm:py-8", image && "border-t-8 border-t-primary"), children: [
+            /* @__PURE__ */ jsx("h1", { className: "text-3xl font-semibold tracking-tight text-balance sm:text-4xl", children: title }),
+            description ? /* @__PURE__ */ jsx("p", { className: "mt-3 text-base text-muted-foreground text-pretty", children: description }) : null,
+            requiredNote ? /* @__PURE__ */ jsx(RequiredNote, { text: requiredNote, className: "mt-4" }) : null
+          ] })
         ]
       }
     );
   }
   return /* @__PURE__ */ jsxs("header", { className: cn("space-y-1", className), children: [
+    image ? /* @__PURE__ */ jsx(HeaderImage, { image, className: "mb-4 rounded-lg" }) : null,
     /* @__PURE__ */ jsx("h1", { className: "text-2xl font-semibold tracking-tight", children: title }),
-    description ? /* @__PURE__ */ jsx("p", { className: "text-muted-foreground", children: description }) : null
+    description ? /* @__PURE__ */ jsx("p", { className: "text-muted-foreground", children: description }) : null,
+    requiredNote ? /* @__PURE__ */ jsx(RequiredNote, { text: requiredNote, className: "pt-1" }) : null
   ] });
 }
 function initials(name) {
@@ -1328,10 +1629,12 @@ function FormBody({
   layout: layoutProp,
   presentation = "embedded",
   brand,
+  theme,
   onSubmit,
   onChange,
   autoAdvance = true,
-  submitLabel = "Submit",
+  submitLabel = "Send",
+  requiredLabel = "Required",
   nextLabel = "OK",
   retryLabel = "Try again",
   slots,
@@ -1468,6 +1771,10 @@ function FormBody({
   };
   const liveRegion = /* @__PURE__ */ jsx("div", { role: "status", "aria-live": "polite", "aria-atomic": "true", className: "sr-only", "data-gf-live": "", children: announcement });
   const presentationValue = { presentation, layout };
+  const themeId = `gf-theme-${useId().replace(/[^a-zA-Z0-9_-]/g, "")}`;
+  const themeStyle = themeCss(theme, `[data-gf-theme="${themeId}"]`);
+  const themed = themeStyle ? { "data-gf-theme": themeId } : {};
+  const styleNode = themeStyle ? /* @__PURE__ */ jsx("style", { children: themeStyle }) : null;
   const brandNode = brand ? renderSlot(DefaultBrand, slots?.brand, { name: brand.name, logo: brand.logo }, slotProps?.brand) : null;
   if (showEnding) {
     const end = def.endings?.find((x) => x.id === ending) ?? def.endings?.[0];
@@ -1482,10 +1789,12 @@ function FormBody({
     );
     return /* @__PURE__ */ jsxs(FormPresentationProvider, { value: presentationValue, children: [
       liveRegion,
+      styleNode,
       page ? /* @__PURE__ */ jsxs(
         "div",
         {
           ref: endingRef,
+          ...themed,
           "data-presentation": "page",
           "data-testid": testID,
           className: cn("flex min-h-dvh w-full flex-col bg-background text-foreground", className),
@@ -1494,7 +1803,7 @@ function FormBody({
             /* @__PURE__ */ jsx("div", { className: "flex flex-1 items-center justify-center px-4 pb-24 pt-8 sm:px-6", children: /* @__PURE__ */ jsx("div", { className: "w-full max-w-xl", children: endingNode }) })
           ]
         }
-      ) : /* @__PURE__ */ jsxs("div", { ref: endingRef, className: cn("mx-auto w-full max-w-xl space-y-6", className), "data-testid": testID, children: [
+      ) : /* @__PURE__ */ jsxs("div", { ref: endingRef, ...themed, className: cn("mx-auto w-full max-w-xl space-y-6", className), "data-testid": testID, children: [
         brandNode,
         endingNode
       ] })
@@ -1543,10 +1852,16 @@ function FormBody({
   }));
   const currentField = pageFocus && current ? engine.field(current) : void 0;
   const keyHint = currentField ? currentField.type === "long-text" ? `${modKey} + Enter` : "Enter \u21B5" : void 0;
+  const hasRequired = def.blocks.some((b) => b.kind === "field" && b.required === true);
   const header = renderSlot(
     DefaultHeader,
     slots?.header,
-    { title: def.title, description },
+    {
+      title: def.title,
+      description,
+      image: theme?.headerImage ? { src: theme.headerImage, alt: theme.headerImageAlt ?? "" } : void 0,
+      requiredNote: hasRequired && requiredLabel ? requiredLabel : void 0
+    },
     slotProps?.header
   );
   const errorSummary = errorItems.length > 0 && layout === "classic" ? renderSlot(
@@ -1602,6 +1917,7 @@ function FormBody({
     slotProps?.navigation
   );
   const formProps = {
+    ...themed,
     ref: formRef,
     noValidate: true,
     onSubmit: handleSubmit,
@@ -1612,6 +1928,7 @@ function FormBody({
   };
   return /* @__PURE__ */ jsxs(FormPresentationProvider, { value: presentationValue, children: [
     liveRegion,
+    styleNode,
     pageFocus ? /* @__PURE__ */ jsxs(
       "form",
       {
@@ -1655,6 +1972,6 @@ function FormBody({
 }
 var classicSection = "rounded-xl border bg-card px-5 py-6 text-card-foreground sm:px-8 has-[[aria-invalid=true]]:border-destructive";
 
-export { FieldChrome, Form, MediaTimeContext, SourceTextContext, builtInRenderers, defaultRegistry, describedBy, useFormPresentation, useMediaTime, useSourceText };
+export { FieldChrome, Form, MediaTimeContext, SourceTextContext, builtInRenderers, defaultRegistry, describedBy, themeColors, themeCss, useFormPresentation, useMediaTime, useSourceText };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map