first commit

docs/ui/react/react-ui/src/components/field-set/field-set.variants.md

@@ -0,0 +1,59 @@
+# FieldSet Variants (cva config)
+
+## Purpose
+
+`fieldSetVariants` and `fieldLegendVariants` are the cva (class-variance-authority) configurations powering `<FieldSet>` and `<FieldLegend>`. They are split from `field-set.tsx` into their own module so an ejected source copy keeps the cva configurations in a dedicated file. Theme overrides flow through `useThemedVariants("FieldSet" | "FieldLegend")`.
+
+These cvas are part of the suaveplan-only `<FieldSet>` addition (no shadcn upstream) — see `field-set.md` for the rationale.
+
+## Features
+
+- `<FieldSet>` carries `flex flex-col gap-3 rounded-md border p-4` so the grouping is visually obvious.
+- `data-[disabled=true]:opacity-70` decay when disabled.
+- `<FieldLegend>` is small bold text (`text-sm font-semibold`) with `data-[invalid=true]:text-destructive` for the error state.
+- NEVER uses `space-y-*` per the shadcn skill rule.
+
+## Usage: Basic Example
+
+```ts
+import { fieldSetVariants, fieldLegendVariants } from "@suaveplan/react-ui";
+
+const fsClass = fieldSetVariants();
+const lgClass = fieldLegendVariants();
+```
+
+## Usage: Advanced Example
+
+```ts
+import { fieldSetVariants, cn } from "@suaveplan/react-ui";
+
+export function CustomFieldSet({
+    children,
+}: {
+    children: React.ReactNode;
+}) {
+    return (
+        <fieldset
+            className={cn(fieldSetVariants(), "shadow-md ring-1 ring-accent")}
+        >
+            {children}
+        </fieldset>
+    );
+}
+```
+
+## API Reference
+
+### `fieldSetVariants(): string`
+
+Returns the fieldset classes.
+
+### `fieldLegendVariants(): string`
+
+Returns the legend classes including the `data-[invalid=true]:text-destructive` selector.
+
+## Implementation Notes
+
+- The `<fieldset>` border + padding are intentionally part of the cva default — most `<FieldSet>` use cases want the visual grouping. Consumers wanting an unstyled fieldset pass `className="border-0 p-0"` (Tailwind class merging via `tailwind-merge` resolves the conflict).
+- The legend's destructive colour is keyed off `data-[invalid=true]` directly rather than via a group selector so the legend can be used outside a `<FieldSet>` without losing the error styling.
+- Per the shadcn skill rule, the cva NEVER uses `space-y-*` — `gap-3` flows the same in RTL.