first commit

2026-05-29 08:20:56 +01:00
commit 949299f58d
6368 changed files with 527176 additions and 0 deletions
--- a/docs/ui/react/react-ui/src/components/status-badge/status-badge.md
+++ b/docs/ui/react/react-ui/src/components/status-badge/status-badge.md
@@ -0,0 +1,97 @@
+# StatusBadge
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs --> - status-badge.variants — `statusBadgeVariants` is th…
+- [status-badge.variants](./status-badge.variants.md) — `statusBadgeVariants` is the cva config that powers the `<StatusBadge>` chassis component. It exposes a `status` axis w…
+- status-badge.variants — `statusBadgeVariants` is th…
+
+- [status-badge.variants](./status-badge.variants.md) — `statusBadgeVariants` is the cva config that powers the `<StatusBadge>` chassis component. It exposes a `status` axis w…
+
+- status-badge.variants — `statusBadgeVariants` is th…
+
+- [status-badge.variants](./status-badge.variants.md) — `statusBadgeVariants` is the cva config that powers the `<StatusBadge>` chassis component. It exposes a `status` axis w…
+
+- status-badge.variants — `statusBadgeVariants` is th…
+
+- [status-badge.variants](./status-badge.variants.md) — `statusBadgeVariants` is the cva config that powers the `<StatusBadge>` chassis component. It exposes a `status` axis w…
+- [status-badge.variants](./status-badge.variants.md) — `statusBadgeVariants` is the cva config that powers the `<StatusBadge>` chassis component. It exposes a `status` axis w…
+
+## Purpose
+
+`<StatusBadge>` is the chassis status marker with semantic colour and matching iconography. It pairs one of five status colour palettes (`success` / `warning` / `error` / `info` / `neutral`) with a default lucide-react icon (`CheckCircle2Icon` / `AlertTriangleIcon` / `XCircleIcon` / `InfoIcon` / `CircleIcon`) so consumers do not hand-roll status-with-icon markers across the application surface.
+
+`<StatusBadge>` is a **suaveplan-only addition** — shadcn does not ship a `status-badge` registry item upstream (per Wave 3a's reconciliation finding #7). The chassis exposes it because every product surface needs status indicators, and hand-rolled spans diverge across teams (different padding, different colours, different iconography). A discrete primitive enforces consistency.
+
+## Features
+
+- Five status colour palettes via the `status` axis (`success` / `warning` / `error` / `info` / `neutral`).
+- Default lucide-react icon per status — overridable via `hideIcon` and a custom child element.
+- Translucent backgrounds with matching borders that meet WCAG AA contrast in both light and dark themes.
+- `data-status` attribute on the rendered element so tests / consumer CSS can target every status badge by status family.
+- `aria-hidden="true"` on the injected icon so the visible text (children) is the accessible name.
+- Forwards refs to the underlying `<div>`.
+
+## Usage: Basic Example
+
+```tsx
+import { StatusBadge } from "@suaveplan/react-ui";
+
+export function StatusRow() {
+    return (
+        <div className="flex flex-wrap gap-2">
+            <StatusBadge status="success">Active</StatusBadge>
+            <StatusBadge status="warning">Pending</StatusBadge>
+            <StatusBadge status="error">Failed</StatusBadge>
+            <StatusBadge status="info">In review</StatusBadge>
+            <StatusBadge status="neutral">Idle</StatusBadge>
+        </div>
+    );
+}
+```
+
+## Usage: Advanced Example
+
+```tsx
+import { StatusBadge } from "@suaveplan/react-ui";
+import { ZapIcon } from "lucide-react";
+
+export function CustomIconStatus() {
+    return (
+        <StatusBadge status="success" hideIcon>
+            <ZapIcon className="size-3" aria-hidden="true" />
+            Lightning fast
+        </StatusBadge>
+    );
+}
+```
+
+## API Reference
+
+### `<StatusBadge>`
+
+`forwardRef<HTMLDivElement, StatusBadgeProps>` — renders a `<div>` with the variant classes + chassis-injected icon (unless `hideIcon === true`) + children.
+
+#### `StatusBadgeProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `status` | `"success" \| "warning" \| "error" \| "info" \| "neutral"` | `"neutral"` | Semantic colour palette + default icon. |
+| `hideIcon` | `boolean` | `false` | When `true`, suppress the chassis-injected icon. Use when children includes a custom icon to avoid double-up. |
+| _all_ `HTMLAttributes<HTMLDivElement>` | _native_ | _native_ | Forwarded as-is. |
+
+#### `statusBadgeVariants`
+
+The bare cva resolver — exported so external consumers (themes, ejected source) can re-use the variants directly.
+
+#### Errors
+
+The StatusBadge component does NOT call `useTranslation()` so it does not interact with the i18n provider. Children are consumer-provided `ReactNode`; consumers using TranslationKey-typed strings should resolve them at the call site (`<StatusBadge>{t('status.active')}</StatusBadge>`).
+
+## Implementation Notes
+
+- The default icon for each status is fixed via the `STATUS_ICON` map. To replace the icon, pass `hideIcon` and provide a custom icon element as the first child — this keeps the chassis API simple while leaving the override path open.
+- `aria-hidden="true"` is applied to the injected icon so the icon does not duplicate the announcement of the status text. When `hideIcon === true` and the consumer provides their own icon, they are responsible for marking it `aria-hidden` themselves.
+- The `data-status` attribute is always written on the rendered `<div>` regardless of whether the icon is shown — this is the canonical hook for tests / consumer CSS targeting status badges by family.
+- The icon size is `size-3` (12px) which matches the badge's `text-xs` typography rhythm; consumers wanting a larger icon should pass `hideIcon` and supply their own sized icon.
+- RTL: the icon sits at the start (logical inline-start) so `dir="rtl"` automatically flips it to the right. No special-case markup needed.