@refineui/react 0.0.1

package/spec/README.md

@@ -0,0 +1,95 @@
+# Component Spec — Contract Layer
+
+**Status: catalog (v1.1)** — all shipped components have Spec JSON; interactive components declare a11y / keyboard / focus / environment where implementation + CSS already satisfy Doctor.
+
+Source of truth for behavior/DOM contracts consumed by Doctor, MCP, and Docs.
+
+```
+packages/react/spec/
+├── manifest.json
+├── schema/component-spec.schema.json
+└── components/*.json
+```
+
+Build copies this tree to `packages/react/dist/spec/` and adds `token-trace-v2.json`, `token-graph.json`, `contract-index.json`.
+
+## Boundaries
+
+| Owns | Does not own |
+|------|----------------|
+| anatomy, variants, states | Tailwind classes / hex |
+| accessibility, keyboard, focus | Usage guides / WCAG essays |
+| layout (logical / RTL) | Full bidirectional layout proof |
+| environment (`forced-colors`, `dir`, …) | Full High Contrast audit |
+| `recipe` string reference | Recipe visual implementation |
+
+```
+Component Spec  →  Doctor (validate declared contracts only)
+                →  MCP (explain)
+                →  Docs SpecRenderer (render declared fields only)
+recipe ref      →  SlotRecipe / defineRecipe (visual)
+                →  Docs ComponentPreview + TokenInspector
+```
+
+## Spec fields (v1)
+
+| Field | Purpose |
+|-------|---------|
+| `anatomy` | Part → `data-refineui` slot |
+| `variants` | Axis → allowed values |
+| `states` | pseudo / component / availability / environment |
+| `dom` | Per-slot state overrides |
+| `accessibility` | Slot a11y contracts |
+| `keyboard` | Key → action (`native` allowed) |
+| `focus` | visual + behavior |
+| `layout` | `direction: logical`, `rtl` |
+| `tokens.visual` | Component token prefix |
+| `recipe` | Recipe name reference |
+
+## Doctor rules (contract)
+
+Doctor validates **declared** fields only. Catalog specs start with anatomy (+ variants / `data-state` where known). Declaring `focus`, `keyboard`, `accessibility`, `layout`, or `forced-colors` opts that component into the matching Doctor rule.
+
+| Rule | Validates |
+|------|-----------|
+| `component-state-contract` | `data-state` literals vs Spec |
+| `accessibility-contract` | required attrs, types, relationships, native |
+| `keyboard-contract` | key handlers (skips `native`) |
+| `focus-contract` | `:focus-visible` + trap/initial/return patterns |
+| `environment-contract` | `forced-colors` + `prefers-contrast` CSS blocks + slots |
+| `layout-contract` | no physical left/right utilities |
+| `state-contract` | `data-refineui` / focus preference |
+| `motion-contract` | reduced-motion / motion roles |
+
+## Coverage
+
+| Surface | Scope |
+|---------|--------|
+| Spec JSON + Docs SpecRenderer | All catalog components in `manifest.json` |
+| Deep a11y / keyboard / focus / environment / layout | Interactive + layout-clean components (Doctor-validated) |
+| Docs ComponentPreview | alert, button, accordion, dialog, badge, switch, checkbox, tabs, select, toast, spinner, chip, tag, segmented-control |
+| SlotRecipe (`defineSlotRecipe`) | alert, accordion, dialog, segmented-control |
+| Single recipe (`defineRecipe`) | button, badge, toast, chip |
+| Docs TokenInspector | alert, button, accordion, dialog, badge, toast, tabs, chip, tag, segmented-control, switch, checkbox, select, spinner |
+
+Environment: `forced-colors` + `prefers-contrast` (CSS in `refineui.css`; Doctor validates both).
+
+### Intentional physical leftovers
+
+Doctor `layout-contract` rejects Tailwind `left`/`right`/`pl`/`ml`/`text-left` utilities. These remain **intentional** (not flagged or deferred):
+
+| Pattern | Where | Why |
+|---------|-------|-----|
+| `-translate-x-1/2` + `start-1/2` | PopOver, Resizable | Horizontal centering; no logical translate utility |
+| `left` / `right` / `translateX(-50%)` | Tooltip panel/arrow | MCP position×align map still physical CSS |
+| `-translate-x-1/2` | Chart x-axis labels | Tick centering under measured SVG positions |
+| Measured `translateX(...)` | Drawer overlay, NavigationMenu indicator | Runtime geometry, not static utilities |
+
+Switch thumb travel uses `translateX` in `refineui.css` with `[dir="rtl"]` negation.
+
+Regenerate baseline then deepen:
+
+```bash
+node packages/react/scripts/expand-component-specs.mjs
+node packages/react/scripts/deepen-component-specs.mjs
+```

package/spec/components/accordion.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "../schema/component-spec.schema.json",
+  "component": "accordion",
+  "version": 1,
+  "export": "Accordion",
+  "anatomy": {
+    "root": "accordion",
+    "item": "accordion-item",
+    "trigger": "accordion-trigger",
+    "panel": "accordion-panel",
+    "content": "accordion-content"
+  },
+  "variants": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "type": [
+      "single",
+      "multiple"
+    ]
+  },
+  "states": {
+    "pseudo": [
+      "focus-visible"
+    ],
+    "component": {
+      "data-state": [
+        "open",
+        "closed"
+      ]
+    },
+    "environment": [
+      "forced-colors",
+      "dir",
+      "prefers-contrast"
+    ]
+  },
+  "attributes": {
+    "data-refineui": "accordion"
+  },
+  "dom": {
+    "accordion-item": {
+      "states": {
+        "component": {
+          "data-state": [
+            "open",
+            "closed"
+          ]
+        }
+      }
+    },
+    "accordion-trigger": {
+      "states": {
+        "pseudo": [
+          "focus-visible"
+        ]
+      }
+    }
+  },
+  "accessibility": {
+    "accordion-trigger": {
+      "element": "button",
+      "role": "button",
+      "requiredAttributes": {
+        "aria-expanded": {
+          "required": true,
+          "type": "boolean"
+        },
+        "aria-controls": {
+          "required": true,
+          "type": "string"
+        }
+      },
+      "relationships": [
+        {
+          "attribute": "aria-controls",
+          "target": "accordion-panel",
+          "targetAttribute": "id",
+          "required": true
+        }
+      ]
+    },
+    "accordion-panel": {
+      "role": "region",
+      "requiredAttributes": {
+        "aria-labelledby": {
+          "required": true,
+          "type": "string"
+        }
+      },
+      "relationships": [
+        {
+          "attribute": "aria-labelledby",
+          "target": "accordion-trigger",
+          "targetAttribute": "id",
+          "required": true
+        }
+      ]
+    }
+  },
+  "keyboard": {
+    "ArrowDown": "next-trigger",
+    "ArrowUp": "previous-trigger",
+    "Home": "first-trigger",
+    "End": "last-trigger"
+  },
+  "focus": {
+    "visual": {
+      "required": true,
+      "selector": ":focus-visible"
+    },
+    "behavior": {
+      "roving": false
+    }
+  },
+  "layout": {
+    "direction": "logical",
+    "rtl": true
+  },
+  "recipe": "accordion",
+  "tokens": {
+    "visual": "accordion"
+  }
+}

package/spec/components/alert.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "../schema/component-spec.schema.json",
+  "component": "alert",
+  "version": 1,
+  "export": "Alert",
+  "anatomy": {
+    "root": "alert",
+    "icon": "alert-icon",
+    "content": "alert-content",
+    "row": "alert-row",
+    "body": "alert-body",
+    "title": "alert-title",
+    "description": "alert-description",
+    "actions": "alert-actions",
+    "action": "alert-action",
+    "close": "alert-close"
+  },
+  "variants": {
+    "variant": [
+      "default",
+      "info",
+      "success",
+      "warning",
+      "danger",
+      "custom"
+    ]
+  },
+  "states": {
+    "pseudo": [
+      "focus-visible"
+    ],
+    "environment": [
+      "forced-colors",
+      "dir",
+      "prefers-contrast"
+    ]
+  },
+  "attributes": {
+    "data-refineui": "alert",
+    "data-variant": "variant"
+  },
+  "dom": {
+    "alert": {
+      "states": {
+        "pseudo": [
+          "focus-visible"
+        ]
+      }
+    }
+  },
+  "accessibility": {
+    "alert": {
+      "element": "div",
+      "role": "alert"
+    }
+  },
+  "focus": {
+    "visual": {
+      "required": true,
+      "selector": ":focus-visible"
+    }
+  },
+  "layout": {
+    "direction": "logical",
+    "rtl": true
+  },
+  "tokens": {
+    "visual": "alert"
+  },
+  "recipe": "alert"
+}

package/spec/components/avatar.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "../schema/component-spec.schema.json",
+  "component": "avatar",
+  "version": 1,
+  "export": "Avatar",
+  "anatomy": {
+    "root": "avatar"
+  },
+  "attributes": {
+    "data-refineui": "avatar"
+  },
+  "variants": {
+    "size": [
+      "xs",
+      "sm",
+      "md",
+      "lg",
+      "xl"
+    ],
+    "layout": [
+      "image",
+      "icon",
+      "initials"
+    ]
+  },
+  "layout": {
+    "direction": "logical",
+    "rtl": true
+  }
+}

package/spec/components/avatars.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "../schema/component-spec.schema.json",
+  "component": "avatars",
+  "version": 1,
+  "export": "Avatars",
+  "anatomy": {
+    "root": "avatars"
+  },
+  "attributes": {
+    "data-refineui": "avatars"
+  },
+  "variants": {
+    "size": [
+      "xs",
+      "sm",
+      "md",
+      "lg",
+      "xl"
+    ],
+    "layout": [
+      "stack",
+      "spread"
+    ]
+  },
+  "layout": {
+    "direction": "logical",
+    "rtl": true
+  }
+}

package/spec/components/badge.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "../schema/component-spec.schema.json",
+  "component": "badge",
+  "version": 1,
+  "export": "Badge",
+  "anatomy": {
+    "root": "badge"
+  },
+  "attributes": {
+    "data-refineui": "badge"
+  },
+  "variants": {
+    "variant": [
+      "default",
+      "neutral",
+      "outline",
+      "success",
+      "warning",
+      "danger"
+    ],
+    "layout": [
+      "label",
+      "number"
+    ]
+  },
+  "layout": {
+    "direction": "logical",
+    "rtl": true
+  },
+  "recipe": "badge",
+  "tokens": {
+    "visual": "badge"
+  },
+  "states": {
+    "environment": [
+      "forced-colors",
+      "dir",
+      "prefers-contrast"
+    ]
+  }
+}

package/spec/components/box.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "../schema/component-spec.schema.json",
+  "component": "box",
+  "version": 1,
+  "export": "Box",
+  "anatomy": {
+    "root": "box"
+  },
+  "attributes": {
+    "data-refineui": "box"
+  },
+  "layout": {
+    "direction": "logical",
+    "rtl": true
+  }
+}

package/spec/components/breadcrumb.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "../schema/component-spec.schema.json",
+  "component": "breadcrumb",
+  "version": 1,
+  "export": "Breadcrumb",
+  "anatomy": {
+    "root": "breadcrumb",
+    "ellipsis": "breadcrumb-ellipsis",
+    "link": "breadcrumb-link",
+    "page": "breadcrumb-page"
+  },
+  "attributes": {
+    "data-refineui": "breadcrumb"
+  },
+  "states": {
+    "pseudo": [
+      "focus-visible"
+    ],
+    "environment": [
+      "forced-colors",
+      "dir"
+    ]
+  },
+  "accessibility": {
+    "breadcrumb-page": {
+      "element": "div",
+      "role": "link"
+    }
+  },
+  "focus": {
+    "visual": {
+      "required": true,
+      "selector": ":focus-visible"
+    }
+  },
+  "layout": {
+    "direction": "logical",
+    "rtl": true
+  }
+}

package/spec/components/bubble.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "../schema/component-spec.schema.json",
+  "component": "bubble",
+  "version": 1,
+  "export": "Bubble",
+  "anatomy": {
+    "root": "bubble",
+    "content": "bubble-content",
+    "group": "bubble-group",
+    "reactions": "bubble-reactions",
+    "surface": "bubble-surface"
+  },
+  "attributes": {
+    "data-refineui": "bubble"
+  },
+  "variants": {
+    "variant": [
+      "default",
+      "secondary",
+      "muted",
+      "tinted",
+      "outline",
+      "ghost",
+      "destructive"
+    ]
+  },
+  "layout": {
+    "direction": "logical",
+    "rtl": true
+  }
+}

package/spec/components/button.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "../schema/component-spec.schema.json",
+  "component": "button",
+  "version": 1,
+  "export": "Button",
+  "anatomy": {
+    "root": "button",
+    "icon": "optional",
+    "label": "required"
+  },
+  "variants": {
+    "variant": [
+      "primary",
+      "secondary",
+      "outline",
+      "ghost"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "layout": [
+      "label",
+      "icon"
+    ]
+  },
+  "states": {
+    "pseudo": [
+      "hover",
+      "active",
+      "focus-visible"
+    ],
+    "availability": [
+      "disabled",
+      "aria-disabled",
+      "data-inactive"
+    ],
+    "component": {
+      "data-state": [
+        "loading"
+      ]
+    },
+    "environment": [
+      "forced-colors",
+      "dir",
+      "prefers-contrast"
+    ]
+  },
+  "attributes": {
+    "data-refineui": "button"
+  },
+  "dom": {
+    "button": {
+      "states": {
+        "pseudo": [
+          "hover",
+          "active",
+          "focus-visible"
+        ],
+        "availability": [
+          "disabled",
+          "aria-disabled",
+          "data-inactive"
+        ],
+        "component": {
+          "data-state": [
+            "loading"
+          ]
+        }
+      }
+    }
+  },
+  "accessibility": {
+    "button": {
+      "element": "button",
+      "native": true
+    }
+  },
+  "keyboard": {
+    "Enter": {
+      "action": "activate",
+      "native": true
+    },
+    "Space": {
+      "action": "activate",
+      "native": true
+    }
+  },
+  "focus": {
+    "visual": {
+      "required": true,
+      "selector": ":focus-visible"
+    }
+  },
+  "layout": {
+    "direction": "logical",
+    "rtl": true
+  },
+  "tokens": {
+    "visual": "button"
+  },
+  "recipe": "button"
+}

package/spec/components/calendar.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "../schema/component-spec.schema.json",
+  "component": "calendar",
+  "version": 1,
+  "export": "Calendar",
+  "anatomy": {
+    "root": "calendar",
+    "day": "calendar-day"
+  },
+  "attributes": {
+    "data-refineui": "calendar"
+  },
+  "states": {
+    "pseudo": [
+      "focus-visible"
+    ],
+    "environment": [
+      "forced-colors",
+      "dir"
+    ]
+  },
+  "accessibility": {
+    "calendar": {
+      "element": "div",
+      "role": "grid"
+    },
+    "calendar-day": {
+      "element": "button",
+      "role": "gridcell"
+    }
+  },
+  "keyboard": {
+    "Enter": {
+      "action": "activate",
+      "native": true
+    },
+    "Space": {
+      "action": "activate",
+      "native": true
+    }
+  },
+  "focus": {
+    "visual": {
+      "required": true,
+      "selector": ":focus-visible"
+    }
+  },
+  "layout": {
+    "direction": "logical",
+    "rtl": true
+  }
+}

package/spec/components/card.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "../schema/component-spec.schema.json",
+  "component": "card",
+  "version": 1,
+  "export": "Card",
+  "anatomy": {
+    "root": "card",
+    "action": "card-action",
+    "content": "card-content",
+    "description": "card-description",
+    "footer": "card-footer",
+    "header": "card-header",
+    "header_main": "card-header-main",
+    "title": "card-title"
+  },
+  "attributes": {
+    "data-refineui": "card"
+  },
+  "variants": {
+    "variant": [
+      "elevated",
+      "outlined"
+    ]
+  },
+  "states": {
+    "component": {
+      "data-state": [
+        "default",
+        "hover",
+        "pressed",
+        "disabled"
+      ]
+    },
+    "environment": [
+      "forced-colors",
+      "dir"
+    ]
+  },
+  "dom": {
+    "card": {
+      "states": {
+        "component": {
+          "data-state": [
+            "default",
+            "hover",
+            "pressed",
+            "disabled"
+          ]
+        }
+      }
+    }
+  },
+  "layout": {
+    "direction": "logical",
+    "rtl": true
+  }
+}