@fragments-sdk/ui 0.17.1 → 0.18.0

package/src/components/Tooltip/Tooltip.contract.json

@@ -0,0 +1,214 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Tooltip",
+  "description": "Contextual help text that appears on hover or focus. Perfect for explaining icons, truncated text, or providing additional context.",
+  "category": "feedback",
+  "tags": [
+    "tooltip",
+    "hint",
+    "help",
+    "hover",
+    "contextual"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Tooltip/index.tsx",
+  "exportName": "Tooltip",
+  "propsSummary": [
+    "children: element (required)",
+    "content: node (required)",
+    "side: top|bottom|left|right (default: top)",
+    "align: start|center|end (default: center)",
+    "sideOffset: number (default: 6)",
+    "delay: number",
+    "closeDelay: number",
+    "disabled: boolean (default: false)",
+    "arrow: boolean (default: true)",
+    "open: boolean",
+    "defaultOpen: boolean",
+    "onOpenChange: function",
+    "contentProps: object",
+    "style: object"
+  ],
+  "props": {
+    "children": {
+      "type": "element",
+      "description": "The element that triggers the tooltip",
+      "required": true
+    },
+    "content": {
+      "type": "node",
+      "description": "Content to display in the tooltip",
+      "required": true
+    },
+    "side": {
+      "type": "enum",
+      "description": "Which side to show the tooltip",
+      "default": "top",
+      "required": false,
+      "values": [
+        "top",
+        "bottom",
+        "left",
+        "right"
+      ]
+    },
+    "align": {
+      "type": "enum",
+      "description": "Alignment along the side",
+      "default": "center",
+      "required": false,
+      "values": [
+        "start",
+        "center",
+        "end"
+      ]
+    },
+    "sideOffset": {
+      "type": "number",
+      "description": "Distance from trigger in pixels",
+      "default": "6",
+      "required": false
+    },
+    "delay": {
+      "type": "number",
+      "description": "Delay before showing (ms)",
+      "default": "400",
+      "required": false
+    },
+    "closeDelay": {
+      "type": "number",
+      "description": "Delay before hiding (ms)",
+      "default": "0",
+      "required": false
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Disable the tooltip",
+      "default": "false",
+      "required": false
+    },
+    "arrow": {
+      "type": "boolean",
+      "description": "Show arrow pointing to trigger",
+      "default": "true",
+      "required": false
+    },
+    "open": {
+      "type": "boolean",
+      "description": "Controlled open state",
+      "required": false
+    },
+    "defaultOpen": {
+      "type": "boolean",
+      "description": "Default open state",
+      "default": "false",
+      "required": false
+    },
+    "onOpenChange": {
+      "type": "function",
+      "description": "Callback when open state changes",
+      "required": false
+    },
+    "contentProps": {
+      "type": "object",
+      "description": "Props forwarded to the tooltip popup element (preferred way to pass popup attrs/className/style)",
+      "required": false
+    },
+    "style": {
+      "type": "object",
+      "description": "",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Explaining icon-only buttons",
+      "Showing full text for truncated content",
+      "Providing keyboard shortcuts",
+      "Brief contextual help that fits in one line"
+    ],
+    "whenNot": [
+      "Long-form help content (use Popover)",
+      "Critical information users must see (use Alert)",
+      "Interactive content (use Popover or Menu)",
+      "Mobile-primary interfaces (tooltips require hover)"
+    ],
+    "guidelines": [
+      "Keep tooltip text concise (under 80 characters)",
+      "Use sentence case, no period for single sentences",
+      "Avoid duplicating visible label text",
+      "Consider mobile users who cannot hover",
+      "Use contentProps for tooltip popup attributes/styling; top-level HTML attrs are applied to the popup for backward compatibility"
+    ],
+    "accessibility": [
+      "Accessible via focus as well as hover",
+      "Uses role=\"tooltip\" with proper aria association",
+      "Delay prevents tooltips from appearing during navigation"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic tooltip on hover",
+      "code": "<Tooltip content=\"Save your changes\">\n  <Button>Save</Button>\n</Tooltip>"
+    },
+    {
+      "name": "Positions",
+      "description": "Tooltips on different sides",
+      "code": "<div style={{ display: 'flex', gap: '16px', padding: '40px' }}>\n  <Tooltip content=\"Top tooltip\" side=\"top\">\n    <Button variant=\"secondary\">Top</Button>\n  </Tooltip>\n  <Tooltip content=\"Bottom tooltip\" side=\"bottom\">\n    <Button variant=\"secondary\">Bottom</Button>\n  </Tooltip>\n  <Tooltip content=\"Left tooltip\" side=\"left\">\n    <Button variant=\"secondary\">Left</Button>\n  </Tooltip>\n  <Tooltip content=\"Right tooltip\" side=\"right\">\n    <Button variant=\"secondary\">Right</Button>\n  </Tooltip>\n</div>"
+    },
+    {
+      "name": "With Shortcut",
+      "description": "Tooltip showing keyboard shortcut",
+      "code": "<Tooltip content=\"Undo (Ctrl+Z)\">\n  <Button variant=\"ghost\">Undo</Button>\n</Tooltip>"
+    },
+    {
+      "name": "No Arrow",
+      "description": "Tooltip without arrow",
+      "code": "<Tooltip content=\"Clean tooltip\" arrow={false}>\n  <Button variant=\"secondary\">Hover me</Button>\n</Tooltip>"
+    },
+    {
+      "name": "With Content Props",
+      "description": "Pass popup attributes/styling using contentProps",
+      "code": "<Tooltip content=\"Custom popup attrs\" contentProps={{ id: 'custom-tooltip-popup' }}>\n  <Button variant=\"secondary\">Hover me</Button>\n</Tooltip>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Popover",
+      "relationship": "alternative",
+      "note": "Use Popover for interactive or longer content"
+    },
+    {
+      "component": "Alert",
+      "relationship": "alternative",
+      "note": "Use Alert for critical information that must be visible"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "content: ReactNode - tooltip content",
+      "side: top|bottom|left|right - position",
+      "delay: number - show delay in ms (default: 400)",
+      "arrow: boolean - show arrow (default: true)",
+      "contentProps: HTMLAttributes<HTMLDivElement> - popup element props"
+    ],
+    "a11yRules": [
+      "A11Y_TOOLTIP_FOCUS",
+      "A11Y_TOOLTIP_ROLE"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root",
+      "Provider"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:07.058Z"
+  }
+}

package/src/components/VisuallyHidden/VisuallyHidden.contract.json

@@ -0,0 +1,116 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "VisuallyHidden",
+  "description": "Hides content visually while keeping it accessible to screen readers. Essential for accessible icon-only buttons and supplementary text.",
+  "category": "navigation",
+  "tags": [
+    "accessibility",
+    "a11y",
+    "screen-reader",
+    "hidden",
+    "sr-only"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/VisuallyHidden/index.tsx",
+  "exportName": "VisuallyHidden",
+  "propsSummary": [
+    "children: node (required)",
+    "as: span|div (default: span)"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Content to hide visually",
+      "required": true
+    },
+    "as": {
+      "type": "enum",
+      "description": "HTML element to render",
+      "default": "span",
+      "required": false,
+      "values": [
+        "span",
+        "div"
+      ]
+    }
+  },
+  "usage": {
+    "when": [
+      "Providing accessible labels for icon-only buttons",
+      "Adding context that screen readers need but sighted users don't",
+      "Hiding decorative content while providing text alternatives",
+      "Skip links for keyboard navigation"
+    ],
+    "whenNot": [
+      "Hiding content from everyone (use display: none or conditional render)",
+      "Content that should be visible on focus (use focus-visible styles)",
+      "Temporarily hidden content (use proper ARIA attributes)",
+      "Lazy-loaded content (use suspense or loading states)"
+    ],
+    "guidelines": [
+      "Always use with icon-only interactive elements",
+      "Keep hidden text concise but descriptive",
+      "Test with screen readers to verify announcements",
+      "Don't overuse; visible text is often better",
+      "VisuallyHidden forwards DOM props and className to the rendered element"
+    ],
+    "accessibility": [
+      "Content is announced by screen readers",
+      "Content is focusable if interactive elements are inside",
+      "Essential for WCAG 2.1 compliance with icon-only controls",
+      "Must convey equivalent information to visual content"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Icon Button Label",
+      "description": "Accessible label for icon-only button",
+      "code": "<button style={{\n  display: 'inline-flex',\n  alignItems: 'center',\n  justifyContent: 'center',\n  width: '40px',\n  height: '40px',\n  border: '1px solid var(--fui-border-default)',\n  borderRadius: '8px',\n  background: 'var(--fui-color-surface-primary)',\n  cursor: 'pointer'\n}}>\n  <svg width=\"20\" height=\"20\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"2\">\n    <path d=\"M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z\" />\n  </svg>\n  <VisuallyHidden>Search</VisuallyHidden>\n</button>"
+    },
+    {
+      "name": "Supplementary Text",
+      "description": "Additional context for screen readers",
+      "code": "<a href=\"#\" style={{ color: 'var(--fui-color-accent)' }}>\n  Read more\n  <VisuallyHidden> about our accessibility features</VisuallyHidden>\n</a>"
+    },
+    {
+      "name": "Skip Link",
+      "description": "Navigation aid that becomes visible on focus",
+      "code": "<div>\n  <VisuallyHidden as=\"div\">\n    <a\n      href=\"#main-content\"\n      style={{\n        position: 'absolute',\n        padding: '8px 16px',\n        background: 'var(--fui-color-accent)',\n        color: 'white'\n      }}\n    >\n      Skip to main content\n    </a>\n  </VisuallyHidden>\n  <p style={{ color: 'var(--fui-color-text-tertiary)', fontSize: '14px' }}>\n    (Screen reader only: \"Skip to main content\" link)\n  </p>\n</div>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Button",
+      "relationship": "child",
+      "note": "Use inside icon-only buttons for accessible labels"
+    },
+    {
+      "component": "Icon",
+      "relationship": "sibling",
+      "note": "Pair with icons to provide text alternatives"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "children: ReactNode - hidden text (required)",
+      "as: span|div - HTML element",
+      "Forwards standard DOM props (id, aria-*, data-*, className, handlers)"
+    ],
+    "a11yRules": [
+      "A11Y_SR_ONLY",
+      "A11Y_ICON_LABEL"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:06.625Z"
+  }
+}

package/src/tokens/_derive.scss

@@ -214,7 +214,10 @@
   }
 
   // Light mode background — stone uses white, colorful palettes use palette[50]
-  $bg: if($palette-name != 'stone', get-shade($palette, 50), #ffffff);
+  $bg: #ffffff;
+  @if $palette-name != 'stone' {
+    $bg: get-shade($palette, 50);
+  }
 
   @return (
     primary: get-shade($palette, 900),           // Main text (high contrast)