@micromerce/formbuilder-react 1.0.982 → 1.0.984

package/README.md

@@ -29,3 +29,73 @@ instead of
 Then run `npm rum watch` to start the formbuilder-react (and changes are automatically applied).<br>
 The other service should now have access to the local lib.<br>
 Warning `...is not a module.` will be displayed, but can be ignored.
+
+## Styling from outside
+
+The formbuilder is styled through CSS custom properties (`--fb-*`, "fb" for formbuilder). Every
+component reads them with its former value as fallback, so **nothing changes unless a host sets
+them** — existing forms look exactly as before (checked story by story against the previous
+release).
+
+### In React
+
+```tsx
+import { FormBuilder, FormBuilderThemeProvider } from "@micromerce/formbuilder-react";
+
+// the webclient design system (micromerce/webclient DESIGN.md) for one form
+<FormBuilder config={config} themePreset="design" />
+
+// a preset plus single tokens, for everything inside the provider
+<FormBuilderThemeProvider preset="design" theme={{ accent: "#058AD7", labelWidth: 160 }}>
+  <FormBuilder config={config} />
+</FormBuilderThemeProvider>
+```
+
+- `theme` is typed (`FormBuilderTheme`); numbers for lengths are taken as px. Single tokens win
+  over the preset; nested providers override the outer one.
+- `FormBuilder` only wraps itself in an element when `theme` or `themePreset` is given.
+- `toCssVars(theme)` returns the custom properties for a `style` prop, for a host that applies
+  the theme to an element of its own (e.g. `<body>`).
+- MUI renders tooltips and menus into a portal under `<body>`; they only see tokens set on
+  `<body>` / `:root` (or on a provider around the portal target).
+
+### In CSS
+
+```css
+.my-form { --fb-color-accent: var(--primary-color); --fb-label-width: 160px; }
+```
+
+or the whole design system with a class on any ancestor: `<body class="fb-theme-design">`.
+
+The default declarations use `:where(:root)` (no specificity), so a host rule always wins.
+
+### Tokens
+
+| `theme` key | Custom property | Default (unchanged) | `design` preset |
+|---|---|---|---|
+| `accent` | `--fb-color-accent` | `#4A96D2` | `var(--primary-color, #4A96D2)` |
+| `accentStrong` | `--fb-color-accent-strong` | the accent | accent 75% mixed with black (`#38709E` for the default) |
+| `accentHover` | `--fb-color-accent-hover` | `#0B5BA6` | accent 60% mixed with black (`#2C5A7E`) |
+| `accentDark` | `--fb-color-accent-dark` | `#255F8E` | the accent hover |
+| `primary` | `--fb-color-primary` | `#4a95d0` | Accent Strong |
+| `label` | `--fb-color-label` | `rgba(0,0,0,.87)` | `rgba(0,0,0,.87)` |
+| `value` | `--fb-color-value` | `rgba(0,0,0,.54)` | `rgba(0,0,0,.87)` |
+| `fieldText` / `fieldFontWeight` | `--fb-color-field-text` / `--fb-field-font-weight` | `#707070` / `300` | `rgba(0,0,0,.87)` / `400` |
+| `placeholder` | `--fb-color-text-placeholder` | `#999` | `rgba(0,0,0,.54)` |
+| `helper` / `helperFontSize` | `--fb-color-helper` / `--fb-helper-font-size` | `#636569` / `10px` | `rgba(0,0,0,.54)` / `12px` |
+| `border` | `--fb-color-border` | `#ccc` | `rgba(0,0,0,.23)` |
+| `borderHover` / `borderFocus` | `--fb-color-border-hover` / `--fb-color-border-focus` | `rgba(0,0,0,.87)` | `rgba(0,0,0,.87)` |
+| `checkboxOff` | `--fb-color-checkbox-off` | `#D0D0D0` | `#D0D0D0` |
+| `background` / `backgroundReadonly` | `--fb-color-bg` / `--fb-color-bg-readonly` | `#fff` / `#e0e0e033` | `#fff` / `rgba(224,224,224,.2)` |
+| `error` | `--fb-color-error` | `#a94442` | `#D32F2F` |
+| `errorFontSize` / `errorIcon` | `--fb-error-font-size` / `--fb-error-icon` | `14px` / none | `12px` / `"\f06a"` |
+| `alertText` / `alertBackground` | `--fb-color-alert-text` / `--fb-color-alert-bg` | `#b01f14` / `#f4433633` | `#D32F2F` / `rgba(211,47,47,.06)` |
+| `labelWidth` / `labelGap` | `--fb-label-width` / `--fb-label-gap` | `200px` / `10px` | unchanged |
+| `inputHeight` / `inputPadding` / `radius` | `--fb-input-height` / `--fb-input-padding` / `--fb-radius` | `40px` / `6px 12px` / `4px` | unchanged |
+| `buttonHeight` / `buttonPadding` / `buttonRadius` / `buttonTextTransform` | `--fb-button-*` | MUI: `36px` / `6px 16px` / `4px` / `uppercase` | unchanged |
+| `focusRing` | `--fb-focus-ring` | none (checkbox: `2px solid #4A96D2`) | `2px solid` accent |
+
+`FORM_BUILDER_TOKENS` lists every key with its property; `styles/theme.module.scss` has the
+preset. Stable class hooks for the rare rule tokens cannot express: `fb-form-group`
+(`--error`), `fb-control-label`, `fb-control-wrapper`, `fb-helper-text`, `fb-error-message`,
+`fb-form-footer`, `fb-submit-button`, `fb-tooltip`. Prefer them over `data-testid` selectors.

package/dist/components/FormBuilder/FormBuilder.d.ts

@@ -2,6 +2,7 @@ import React from "react";
 import type { PostMessageProps, PostMessageResponse } from "../../types";
 import { FileUploaderConfig, FormBuilderConfig, resolveUrl } from "../../types";
 import type { controlProps } from "../../types/controlProps";
+import type { FormBuilderTheme, FormBuilderThemePreset } from "../../theme";
 import type { queryControl } from "../QueryControl/data/defaultControls";
 import "../../styles/theme.module.scss";
 import { IFormState } from "./utils/extractFormControlValues";
@@ -18,8 +19,10 @@ export interface IProps {
     onValidationFail?: () => void;
     postGenAiMessage?: ({ message, profile, }: PostMessageProps) => Promise<PostMessageResponse>;
     onChange?: (fieldId: string, value: string | string[]) => void;
+    themePreset?: FormBuilderThemePreset;
+    theme?: FormBuilderTheme;
 }
-declare const FormBuilder: ({ config, controlProps, customControls, fileUploaderConfig, iconType, state, resolveUrl, onSubmit, onValidationFail, postGenAiMessage, onChange, }: IProps) => React.JSX.Element | undefined;
+declare const FormBuilder: ({ config, controlProps, customControls, fileUploaderConfig, iconType, state, resolveUrl, onSubmit, onValidationFail, postGenAiMessage, onChange, themePreset, theme, }: IProps) => React.JSX.Element | undefined;
 interface FormProps {
     method: string;
     formSubmitted: boolean;