Initial Commit

packages/ui/react/react-ui/src/components/label/label.variants.md

@@ -0,0 +1,48 @@
+# Label Variants (cva config)
+
+## Purpose
+
+`labelVariants` is the cva (class-variance-authority) configuration that powers every `<Label>` render. It is split from `label.tsx` into its own module so an ejected source copy under `npx shadcn@latest add @suaveplan/label` keeps the cva configuration in a dedicated file — exactly mirroring the upstream shadcn convention. Theme overrides flow through `useThemedVariants("Label", labelVariants)`, so the runtime cva resolver can be replaced or extended by an active `ThemePlugin` without touching the component source.
+
+The module exports a single `labelVariants` callable resolver (`(props?) => string`) tagged with the component name `"Label"` via `defineVariants`. Consumers that want the bare resolver — for example to render the same label styling on a non-`<label>` element such as `<legend>` — import `labelVariants` directly and apply the result via `cn()` themselves.
+
+## Features
+
+- Single `default` cva variant + single `default` size — the shadcn upstream Label recipe is structurally simple; the chassis follows suit so themes carry the variation.
+- `peer-disabled:cursor-not-allowed peer-disabled:opacity-70` so a label adjacent to a `peer`-classed disabled input automatically picks up the visual decay without consumer plumbing.
+- `data-[disabled=true]:cursor-not-allowed data-[disabled=true]:opacity-70` so the chassis-supplied `disabled` prop drives the same visual decay even without a sibling input.
+- `text-sm font-medium leading-none` for the chassis baseline label typography.
+
+## Usage: Basic Example
+
+```ts
+import { labelVariants } from "@suaveplan/react-ui";
+
+const className = labelVariants({ variant: "default", size: "default" });
+```
+
+## Usage: Advanced Example
+
+```ts
+import { labelVariants, cn } from "@suaveplan/react-ui";
+
+export function FieldsetLegend({ children }: { children: React.ReactNode }) {
+    return (
+        <legend className={cn(labelVariants({}), "px-2 text-base")}>
+            {children}
+        </legend>
+    );
+}
+```
+
+## API Reference
+
+### `labelVariants(props?: VariantProps<typeof labelVariants>): string`
+
+Returns the cva-merged class string for the supplied variant + size combination. Both fields are optional; omitted fields fall back to the cva `defaultVariants` (`variant: "default"`, `size: "default"`).
+
+## Implementation Notes
+
+- The resolver is tagged with `componentName: "Label"` (non-enumerable, non-writable) via `defineVariants` so debug tooling can identify the cva instance at runtime.
+- The chassis prefers the `peer-disabled` pattern over the chassis `disabled` prop when wiring labels next to inputs — passing `disabled` to both elements is redundant and risks drift between visual and functional state.
+- The cva base is intentionally minimal — labels routinely interleave dynamic inline elements (asterisks for required fields, badge counts, helper-text indicators) and the cva config does not attempt to style any of those; consumer composition owns them.