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

package/agent-docs/external/kuat-agent-rules/reference/media-types/web-product/patterns/documentation.md

@@ -1,19 +1,18 @@
-# Documentation Scenarios
+# Documentation
 
-Patterns for documentation sites, knowledge bases, API references, and content-heavy pages.
+**User goal:** Find information quickly, understand it, complete tasks with step-by-step guidance, and
+stay oriented throughout.
 
----
+> **Pattern:** *Pages* · single-medium (web-product) — concept and implementation together.
+> Covers documentation sites, knowledge bases, API references, and content-heavy pages.
 
-## Principles
-
-### User Goals
+## Context
 
-- **Find information quickly** - Search and navigate efficiently
-- **Understand content** - Clear, well-structured explanations
-- **Complete tasks** - Step-by-step guidance that works
-- **Stay oriented** - Know where they are and where to go next
+Documentation is where users go to find information, understand how something works, and complete tasks.
+They want to search and navigate efficiently, read clear and well-structured explanations, follow
+step-by-step guidance that works, and always know where they are and where to go next.
 
-### UX Principles
+## Principles
 
 | Principle | Implementation |
 |-----------|----------------|
@@ -22,22 +21,18 @@ Patterns for documentation sites, knowledge bases, API references, and content-h
 | Multiple paths | Search, navigation, breadcrumbs |
 | Progressive detail | Overview first, details on demand |
 
-### Success Metrics
+Success shows up as: search effectiveness (found what they needed), time to find information, page bounce
+rate, and task completion rate for tutorials.
 
-- Search effectiveness (found what they needed)
-- Time to find information
-- Page bounce rate
-- Task completion rate (for tutorials)
+## Solution in web-product
 
----
-
-## Layout
+### Layout
 
 **Base Layout:** Sidebar Navigation + Split Layout
 
 Documentation uses a three-column layout on desktop:
 
-### Docs Landing Page
+#### Docs Landing Page
 
 Use Horizontal Navigation:
 
@@ -57,7 +52,7 @@ Use Horizontal Navigation:
 └─────────────────────────────────────┘
 ```
 
-### Docs Content Page
+#### Docs Content Page
 
 Use Sidebar + Split (three-column):
 
@@ -77,7 +72,7 @@ Use Sidebar + Split (three-column):
 └──────┴──────────────────────────────────┘
 ```
 
-### Specifications
+#### Specifications
 
 | Element | Value |
 |---------|-------|
@@ -86,11 +81,9 @@ Use Sidebar + Split (three-column):
 | Content max-width | 800px (prose) |
 | Content padding | 32-48px |
 
----
-
-## Design
+### Design
 
-### Color Tokens
+#### Color Tokens
 
 | Element | Token |
 |---------|-------|
@@ -101,7 +94,7 @@ Use Sidebar + Split (three-column):
 | Inline code | `bg-muted` |
 | Links | `text-primary` |
 
-### Typography
+#### Typography
 
 | Element | Style |
 |---------|-------|
@@ -112,7 +105,7 @@ Use Sidebar + Split (three-column):
 | Code | `font-mono text-sm` |
 | Sidebar nav | `text-sm` |
 
-### Navigation Sidebar
+#### Navigation Sidebar
 
 | Element | Specification |
 |---------|---------------|
@@ -123,7 +116,7 @@ Use Sidebar + Split (three-column):
 | Sub-pages | Indented, smaller text |
 | Scroll | Independent from content |
 
-### Table of Contents (Right)
+#### Table of Contents (Right)
 
 | Element | Specification |
 |---------|---------------|
@@ -132,11 +125,9 @@ Use Sidebar + Split (three-column):
 | Active tracking | Highlight current section on scroll |
 | Visibility | Hide below 1280px |
 
----
+### Content
 
-## Content
-
-### Page Structure
+#### Page Structure
 
 ```markdown
 # Page Title           ← H1, one per page
@@ -150,7 +141,7 @@ Intro paragraph        ← No heading, describes page purpose
 #### Detail            ← H4, use sparingly
 ```
 
-### Navigation Hierarchy
+#### Navigation Hierarchy
 
 ```
 Getting Started        ← Category (bold, not clickable)
@@ -163,7 +154,7 @@ Components             ← Category
     Examples           ← Sub-page
 ```
 
-### Breadcrumbs
+#### Breadcrumbs
 
 ```
 Docs / Components / Button / Variants
@@ -173,7 +164,7 @@ Docs / Components / Button / Variants
 - All items clickable except current
 - Truncate middle items on mobile if needed
 
-### Previous/Next Navigation
+#### Previous/Next Navigation
 
 ```
 ┌─────────────────────────────────────────┐
@@ -186,9 +177,7 @@ Docs / Components / Button / Variants
 - Based on sidebar navigation order
 - Show page titles, not just "Previous/Next"
 
----
-
-## Accessibility
+### Accessibility
 
 **Base requirements:** See [accessibility foundations](../../../accessibility/accessibility.md) and [web accessibility](../accessibility.md)
 
@@ -203,18 +192,16 @@ Docs / Components / Button / Variants
 | Code blocks | Scrollable with keyboard, screen reader context |
 | Multiple nav labels | `aria-label` to distinguish left vs right sidebars |
 
-### Code Blocks
+#### Code Blocks
 
 - Ensure code blocks are keyboard scrollable
 - Provide language context for screen readers
 - Copy button must be keyboard accessible
 - Don't rely on syntax highlighting alone for meaning
 
----
-
-## Implementation
+### Implementation
 
-### Code Block Patterns
+#### Code Block Patterns
 
 **Inline Code:**
 
@@ -248,7 +235,7 @@ Docs / Components / Button / Variants
 - Preserve selection across page navigation
 - Accessible tab panel pattern
 
-### Search Patterns
+#### Search Patterns
 
 **Search Bar:**
 
@@ -264,7 +251,7 @@ Docs / Components / Button / Variants
 - Keyboard navigation (arrows + enter)
 - Recent searches
 
-### Table of Contents Behavior
+#### Table of Contents Behavior
 
 | Behavior | Implementation |
 |----------|----------------|
@@ -274,7 +261,7 @@ Docs / Components / Button / Variants
 | Hide on small screens | Below 1280px |
 | Collapse | Optionally collapsible |
 
-### Responsive Behavior
+#### Responsive Behavior
 
 | Breakpoint | Left Sidebar | Content | Right Sidebar |
 |------------|--------------|---------|---------------|
@@ -282,8 +269,6 @@ Docs / Components / Button / Variants
 | Tablet | Collapsible | Full width | Hidden |
 | Desktop | Visible (240px) | Centered (max 800px) | Visible (200px) |
 
----
-
 ## Best Practices
 
 ### Do's
@@ -324,9 +309,14 @@ Docs / Components / Button / Variants
 | External links | Mark with icon, open in new tab |
 | Deprecated content | Clear warnings, link to current |
 
----
+## Examples
+
+The three-column docs content page above is the canonical mid-fidelity frame: a left navigation sidebar
+(240-280px) with the doc tree, a centred prose column (max 800px) carrying breadcrumbs, title, and body,
+and a sticky right-hand "On This Page" table of contents. The docs landing page is the same system in a
+horizontal-nav variant — hero search, category cards, popular articles — with the sidebar dropped.
 
-## Related Documentation
+## Related
 
 - [Product Design](../design.md) - Sidebar and Split layouts
 - [Accessibility foundations](../../../accessibility/accessibility.md) - Structure and headings

package/agent-docs/external/kuat-agent-rules/reference/media-types/web-product/patterns/{authentication.md → sign-in.md}

@@ -1,42 +1,38 @@
-# Authentication Scenarios
+# Help users to sign in
 
-Patterns for login, registration, password flows, and account verification.
+**User goal:** Get into the product quickly and securely, and recover access without friction when a
+password is forgotten.
 
----
+> **Pattern:** *Help users to…* · single-medium (web-product) — concept and implementation together.
+> Covers login, registration, password reset, and MFA / code entry.
 
-## Principles
-
-### User Goals
+## Context
 
-- **Get in quickly** - Authentication is a barrier to the actual task
-- **Feel secure** - Trust that credentials are protected
-- **Recover easily** - Forgot password shouldn't be frustrating
+Authentication is a barrier to the user's real task. Users want to get in quickly, trust that their
+credentials are protected, and recover easily when something goes wrong. It is the first impression of
+the product's competence, so friction and unclear errors here cost disproportionately.
 
-### UX Principles
+## Principles
 
-| Principle | Implementation |
+| Principle | What it means |
 |-----------|----------------|
 | Minimise friction | Only ask for essential information |
 | Clear feedback | Immediate, helpful error messages |
 | Maintain trust | Security indicators, clear privacy info |
 | Support recovery | Easy password reset, account recovery |
 
-### Success Metrics
+Success shows up as: time to complete login/registration, password-reset completion rate, error and
+recovery rates, and abandonment rate.
 
-- Time to complete login/registration
-- Password reset completion rate
-- Error rate and recovery success
-- Abandonment rate
+## Solution in web-product
 
----
-
-## Layout
+### Layout
 
 **Base Layout:** Single Column
 
 Authentication pages should minimise distraction and focus users on the task.
 
-### Page Structure
+#### Page Structure
 
 ```
 ┌─────────────────────────────────────────┐
@@ -59,7 +55,7 @@ Authentication pages should minimise distraction and focus users on the task.
 └─────────────────────────────────────────┘
 ```
 
-### Specifications
+#### Specifications
 
 | Element | Value |
 |---------|-------|
@@ -71,23 +67,21 @@ Authentication pages should minimise distraction and focus users on the task.
 | Minimum viewport height | 100vh |
 | Logo placement | Centered above card, or inside card header |
 
-### Header
+#### Header
 
 - **Minimal navigation** - Logo only, no full navigation
 - Logo links to marketing site or app home
 - No distracting elements
 
-### Footer
+#### Footer
 
 - Minimal: legal links only (Privacy Policy, Terms)
 - Copyright notice optional
 - No marketing content
 
----
-
-## Design
+### Design
 
-### Color Tokens
+#### Color Tokens
 
 | Element | Token |
 |---------|-------|
@@ -98,7 +92,7 @@ Authentication pages should minimise distraction and focus users on the task.
 | Error text | `text-destructive` |
 | Link text | `text-primary` |
 
-### Typography
+#### Typography
 
 | Element | Style |
 |---------|-------|
@@ -109,7 +103,7 @@ Authentication pages should minimise distraction and focus users on the task.
 | Error messages | `text-sm text-destructive` |
 | Links | `text-sm text-primary underline` |
 
-### Spacing
+#### Spacing
 
 | Element | Spacing |
 |---------|---------|
@@ -119,11 +113,9 @@ Authentication pages should minimise distraction and focus users on the task.
 | Form to button | 24px |
 | Button to secondary link | 16px |
 
----
+### Content
 
-## Content
-
-### Login Page
+#### Login Page
 
 **Required Elements:**
 
@@ -146,7 +138,7 @@ Authentication pages should minimise distraction and focus users on the task.
 | Forgot link | "Forgot your password?" |
 | Register link | "Don't have an account? Sign up" |
 
-### Registration Page
+#### Registration Page
 
 **Required Elements:**
 
@@ -166,7 +158,7 @@ Authentication pages should minimise distraction and focus users on the task.
 - Unmet: `text-muted-foreground`
 - Met: `text-green-600` with checkmark
 
-### Password Reset Flow
+#### Password Reset Flow
 
 **Step 1: Request Reset**
 
@@ -181,16 +173,14 @@ Authentication pages should minimise distraction and focus users on the task.
 - Password requirements visible
 - "Reset password" button
 
-### MFA / Code Entry
+#### MFA / Code Entry
 
 - 6-digit code input (individual boxes or single field)
 - "Resend code" link with countdown timer
 - "Use different method" secondary action
 - Clear instructions on where code was sent
 
----
-
-## Accessibility
+### Accessibility
 
 **Base requirements:** See [accessibility foundations](../../../accessibility/accessibility.md) and [web accessibility](../accessibility.md)
 
@@ -205,7 +195,7 @@ Authentication pages should minimise distraction and focus users on the task.
 | Password toggle | Toggle button is keyboard accessible |
 | Error announcement | Screen reader announces errors on submit |
 
-### Form Validation
+#### Form Validation
 
 Follow the standard validation pattern:
 
@@ -215,11 +205,9 @@ Follow the standard validation pattern:
 - **Error summary** - Show summary at top with links to fields
 - **Focus first error** - Move focus to first invalid field
 
----
-
-## Implementation
+### Implementation
 
-### Button Placement
+#### Button Placement
 
 **Component guide:** `shadcn:button` — the `components/button.md` guide lives in the consumer package or overlay (see [component-registry.md](../component-registry.md)).
 
@@ -229,7 +217,7 @@ Follow the standard validation pattern:
 | Secondary link | Below button, centered | Text link |
 | Forgot password | Below password field, right | Text link |
 
-### Error States
+#### Error States
 
 | Error Type | Display Location |
 |------------|-----------------|
@@ -238,7 +226,7 @@ Follow the standard validation pattern:
 | Rate limiting | Alert above form with wait time |
 | Network error | Alert above form with retry option |
 
-### Security Considerations
+#### Security Considerations
 
 | Requirement | Implementation |
 |-------------|----------------|
@@ -247,7 +235,7 @@ Follow the standard validation pattern:
 | Password visibility | Toggle with clear state indication |
 | Session timeout | Warn before logging out |
 
-### Responsive Behavior
+#### Responsive Behavior
 
 | Breakpoint | Behavior |
 |------------|----------|
@@ -255,8 +243,6 @@ Follow the standard validation pattern:
 | Tablet | Centered card, 400px max |
 | Desktop | Centered card, 400px max |
 
----
-
 ## Best Practices
 
 ### Do's
@@ -294,10 +280,14 @@ Follow the standard validation pattern:
 | Email not verified | Offer to resend verification |
 | Session expired mid-flow | Preserve form data, prompt re-authentication |
 
----
+## Examples
+
+The single centred auth card above (max 400px, logo centred, primary action full-width) is the canonical
+mid-fidelity frame. The same frame serves login, registration, password reset, and MFA — the fields and
+microcopy change, the layout does not.
 
-## Related Documentation
+## Related
 
 - [Product Design](../design.md) - Layout patterns
 - [Web Accessibility](../accessibility.md) - Form validation pattern
-- [Forms Pattern](./forms.md) - General form patterns
+- [Help users to complete a form](./complete-a-form.md) - General form patterns

package/agent-docs/manifest.json

@@ -1,8 +1,8 @@
 {
-  "packageVersion": "0.14.0",
+  "packageVersion": "0.15.0-beta.1",
   "rules": {
-    "snapshotRef": "57ee7c45da823106c63d8e6ca6f19bf1ce9efdde",
-    "snapshotDate": "2026-07-01T17:20:19.344Z",
+    "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:** 57ee7c45da82
+**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';