@equal-experts/kuat-react 0.15.0-beta.0 → 0.15.0-beta.1

package/agent-docs/AGENTS.md

@@ -7,4 +7,4 @@ Rules for this install live under `agent-docs/` in `@equal-experts/kuat-core`, `
 3. Load component guides via `agent-docs/components/components.manifest.json`.
 4. Skills: `kuat-review`, `kuat-create` from [kuat-agent-docs](https://github.com/equalexperts/kuat-agent-docs).
 
-**Version:** 0.15.0-beta.0 · **Rules snapshot:** 24ebd2dee5cc
+**Version:** 0.15.0-beta.1 · **Rules snapshot:** 038a985b57fe

package/agent-docs/README.md

@@ -14,4 +14,4 @@ Curated agent docs bundled with `@equal-experts/kuat-core`, `@equal-experts/kuat
 node scripts/agent-docs/bundle-for-core.mjs
 ```
 
-Built against upstream ref: `24ebd2dee5cc`
+Built against upstream ref: `038a985b57fe`

package/agent-docs/components/callout.md

@@ -0,0 +1,66 @@
+# Callout (`kuat:callout`)
+
+## Overview
+
+Inline banner for surfacing a status message tied to a section of content: info, positive, warning, or issue. Supports a required title, an optional description, a per-type icon (shown by default, can be hidden), and an optional link-style action. Exported from `@equal-experts/kuat-react` / `@equal-experts/kuat-vue`.
+
+## When to use
+
+- Persistent, in-page status messages tied to a section of content (e.g. explaining what a view shows, or that a save failed)
+- Confirmations, warnings, or errors that should stay visible until the user navigates away or dismisses them via the action link
+
+## When not to use
+
+- Transient, self-dismissing notifications — use `Sonner`
+- Form field-level validation — use `Field`'s error slot
+- A single inline icon+label with no message — use `Badge`
+
+## Variants
+
+Four semantic `type` values, each with its own background tint and left border/icon accent:
+
+- `info` (default) — ee-blue tint, `Info` icon
+- `positive` — uptime-green tint, `CheckCircle2` icon
+- `warning` — equal-ember tint, `AlertTriangle` icon
+- `issue` — runtime-red tint, `XCircle` icon
+
+## States
+
+- **Icon shown / hidden** — `icon` prop, default `true`. The icon glyph is chosen automatically from `type`; consumers cannot swap it independently.
+- **With / without description** — omit `description` to render title only.
+- **With / without action** — omit `action` to render no link. Only a link-style action ships in this release; additional action kinds (e.g. a button) may be added in future without changing the `title`/`description`/`icon` API.
+
+## Content guidance
+
+- Title should be a short, complete statement of the status — it's the only text guaranteed to be read, since colour is never the sole signal (icon shape + title wording both carry the meaning, independent of the accent colour).
+- Description is for supporting detail, not another restatement of the title.
+- Action label should describe the action's effect (e.g. "Close message"), not just "Click here".
+
+## Behaviour
+
+- Root element renders `role="status"` (polite live region) — appropriate for a persistent banner already present in the page, as opposed to a toast that should interrupt.
+- The action renders as a real `<a href>` (with optional `target` and `onClick`), not a button — it's always a navigation/link affordance in this release.
+
+## Accessibility
+
+- Status is never conveyed by colour alone: the icon shape (circle-i / check / triangle / x) and the title wording both signal the type independent of colour (WCAG 1.4.1).
+- The icon and title text share the same neutral `--foreground` token — only the left border stripe and background use the per-type accent colour, so the icon remains legible regardless of type.
+- All four `background`/`foreground` token pairs (`--callout-info`, `--callout-positive`, `--callout-warning`, `--callout-issue`, each with a `-foreground` counterpart) are covered by `pnpm tokens:contrast-check` in both light and dark mode.
+- Icon is `aria-hidden="true"` — it's decorative reinforcement of the title text, not a separate accessible element.
+
+## API
+
+Import from `@equal-experts/kuat-react` (subpath: `@equal-experts/kuat-react/callout`) or `@equal-experts/kuat-vue` (subpath: `@equal-experts/kuat-vue/callout`).
+
+- `type?: "info" | "positive" | "warning" | "issue"` — default `"info"`
+- `title` — required
+- `description?` — optional
+- `icon?: boolean` — default `true`
+- `action?: { label: string; href: string; target?: string; onClick?: (event) => void }` — optional
+
+See Storybook (`Feedback/Callout`) for live examples of every type and combination.
+
+## Related components
+
+- `shadcn:sonner` (Kuat `Sonner`) — transient, self-dismissing toast notifications
+- `kuat:field` — inline form-field validation messages

package/agent-docs/components/components.manifest.json

@@ -18,6 +18,12 @@
       "displayName": "KuatHeader",
       "path": "components/kuat-header.md",
       "sources": ["@equal-experts/kuat-react", "@equal-experts/kuat-vue"]
+    },
+    "kuat:callout": {
+      "slug": "callout",
+      "displayName": "Callout",
+      "path": "components/callout.md",
+      "sources": ["@equal-experts/kuat-react", "@equal-experts/kuat-vue"]
     }
   }
 }

package/agent-docs/manifest.json

@@ -1,8 +1,8 @@
 {
-  "packageVersion": "0.15.0-beta.0",
+  "packageVersion": "0.15.0-beta.1",
   "rules": {
-    "snapshotRef": "24ebd2dee5cc5153859fd56beb166826f4d98e3a",
-    "snapshotDate": "2026-07-06T10:02:11.557Z",
+    "snapshotRef": "038a985b57fe567a24d3a663277f4594d75b9a87",
+    "snapshotDate": "2026-07-06T14:20:52.535Z",
     "sourceRepo": "equalexperts/kuat-agent-docs",
     "loadingPath": "agent-docs/rules/LOADING-consumer.md"
   }

package/agent-docs/rules/LOADING-consumer.md

@@ -2,7 +2,7 @@
 
 **Package:** @equal-experts/kuat-core (and mirrored in kuat-react / kuat-vue agent-docs)
 
-**Snapshot:** 24ebd2dee5cc
+**Snapshot:** 038a985b57fe
 
 ## Default load (web product / marketing UI)
 

package/dist/callout-DFmAtUwR.js

@@ -0,0 +1,46 @@
+import { jsxs as c, jsx as t } from "react/jsx-runtime";
+import * as d from "react";
+import { XCircle as m, AlertTriangle as _, CheckCircle2 as f, Info as C } from "lucide-react";
+import { c as h } from "./utils-DLUjLwnh.js";
+const T = ["info", "positive", "warning", "issue"], p = {
+  info: C,
+  positive: f,
+  warning: _,
+  issue: m
+}, N = d.forwardRef(function({ className: e, type: a = "info", title: s, description: o, icon: n = !0, action: l, ...i }, r) {
+  const u = p[a];
+  return /* @__PURE__ */ c(
+    "div",
+    {
+      ref: r,
+      role: "status",
+      "data-slot": "callout",
+      "data-type": a,
+      className: h("callout", `callout--${a}`, e),
+      ...i,
+      children: [
+        n ? /* @__PURE__ */ t(u, { "aria-hidden": "true", className: "callout__icon", "data-slot": "callout-icon" }) : null,
+        /* @__PURE__ */ t("div", { className: "callout__content", "data-slot": "callout-content", children: /* @__PURE__ */ c("div", { className: "callout__text-content", children: [
+          /* @__PURE__ */ t("p", { className: "callout__title", "data-slot": "callout-title", children: s }),
+          o != null ? /* @__PURE__ */ t("p", { className: "callout__description", "data-slot": "callout-description", children: o }) : null,
+          l ? /* @__PURE__ */ t(
+            "a",
+            {
+              className: "callout__action",
+              "data-slot": "callout-action",
+              href: l.href,
+              target: l.target,
+              onClick: l.onClick,
+              children: l.label
+            }
+          ) : null
+        ] }) })
+      ]
+    }
+  );
+});
+N.displayName = "Callout";
+export {
+  N as C,
+  T as a
+};

package/dist/callout.d.ts

@@ -0,0 +1,3 @@
+export { cn } from './lib/utils';
+export { Callout, CALLOUT_TYPES } from './components/ui/callout';
+export type { CalloutProps, CalloutType, CalloutAction } from './components/ui/callout';

package/dist/callout.js

@@ -0,0 +1,7 @@
+import { c as r } from "./utils-DLUjLwnh.js";
+import { a as t, C } from "./callout-DFmAtUwR.js";
+export {
+  t as CALLOUT_TYPES,
+  C as Callout,
+  r as cn
+};

package/dist/components/ui/callout/callout.d.ts

@@ -0,0 +1,19 @@
+import { KuatSlotContent } from '../../../lib/react-node-compat';
+import * as React from "react";
+export declare const CALLOUT_TYPES: readonly ["info", "positive", "warning", "issue"];
+export type CalloutType = (typeof CALLOUT_TYPES)[number];
+export interface CalloutAction {
+    label: string;
+    href: string;
+    target?: React.HTMLAttributeAnchorTarget;
+    onClick?: React.MouseEventHandler<HTMLAnchorElement>;
+}
+export interface CalloutProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+    type?: CalloutType;
+    title: KuatSlotContent;
+    description?: KuatSlotContent;
+    icon?: boolean;
+    action?: CalloutAction;
+}
+declare const Callout: React.ForwardRefExoticComponent<CalloutProps & React.RefAttributes<HTMLDivElement>>;
+export { Callout };

package/dist/components/ui/callout/index.d.ts

@@ -0,0 +1,2 @@
+export { Callout, CALLOUT_TYPES } from './callout';
+export type { CalloutProps, CalloutType, CalloutAction } from './callout';

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export { ButtonGroup, ButtonGroupSeparator, ButtonGroupText, buttonGroupVariants
 export type { ButtonGroupProps, ButtonGroupTextProps, ButtonGroupSeparatorProps, ButtonGroupOrientation, } from './components/ui/button-group';
 export { ContentCard } from './components/ui/content-card';
 export type { ContentCardProps } from './components/ui/content-card';
+export { Callout, CALLOUT_TYPES } from './components/ui/callout';
+export type { CalloutProps, CalloutType, CalloutAction, } from './components/ui/callout';
 export { KuatHeader, kuatHeaderVariants, EELogo, KUAT_HEADER_LOCKUP_VARIANTS, KUAT_HEADER_APP_SWITCHER_EMPTY, } from './components/ui/kuat-header';
 export type { KuatHeaderProps, EELogoProps, KuatHeaderVariant, KuatHeaderLockupVariant, KuatHeaderSubItem, KuatHeaderNavItem, KuatHeaderAccountItem, KuatHeaderAccountConfig, KuatHeaderAccountLabels, KuatHeaderAccountMobileTier, KuatHeaderActionItem, KuatHeaderApp, KuatHeaderAppSwitcherConfig, KuatHeaderAppSwitcherEmpty, KuatHeaderAppSwitcherLabels, KuatHeaderLockupConfig, } from './components/ui/kuat-header';
 export { shouldShowAppSwitcher, resolveAppSwitcherLabels, resolveHeaderLockup, } from './components/ui/kuat-header';