@usefragments/ui 1.5.4 → 1.7.0

package/src/components/Tooltip/index.tsx

@@ -1,17 +1,20 @@
-'use client';
+"use client";
 
-import * as React from 'react';
-import { Tooltip as BaseTooltip } from '@base-ui/react/tooltip';
-import styles from './Tooltip.module.scss';
+import * as React from "react";
+import { Tooltip as BaseTooltip } from "@base-ui/react/tooltip";
+import styles from "./Tooltip.module.scss";
 
 // ============================================
 // Types
 // ============================================
 
-export type TooltipSide = 'top' | 'bottom' | 'left' | 'right';
-export type TooltipAlign = 'start' | 'center' | 'end';
+export type TooltipSide = "top" | "bottom" | "left" | "right";
+export type TooltipAlign = "start" | "center" | "end";
 
-export interface TooltipProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'content' | 'defaultChecked'> {
+export interface TooltipProps extends Omit<
+  React.HTMLAttributes<HTMLDivElement>,
+  "content" | "defaultChecked"
+> {
   /** The element that triggers the tooltip */
   children: React.ReactElement;
   /** Content to display in the tooltip */
@@ -76,8 +79,8 @@ const TooltipProviderContext = React.createContext(false);
 function TooltipRoot({
   children,
   content,
-  side = 'top',
-  align = 'center',
+  side = "top",
+  align = "center",
   sideOffset = 6,
   delay,
   closeDelay,
@@ -101,9 +104,9 @@ function TooltipRoot({
       for (const [key, triggerHandler] of Object.entries(triggerProps)) {
         const childHandler = childProps[key];
         if (
-          key.startsWith('on') &&
-          typeof triggerHandler === 'function' &&
-          typeof childHandler === 'function'
+          key.startsWith("on") &&
+          typeof triggerHandler === "function" &&
+          typeof childHandler === "function"
         ) {
           mergedProps[key] = (...args: unknown[]) => {
             (childHandler as (...event: unknown[]) => void)(...args);
@@ -114,7 +117,7 @@ function TooltipRoot({
 
       return React.cloneElement(children, mergedProps);
     },
-    [children],
+    [children]
   );
 
   if (disabled || !children) {
@@ -128,11 +131,7 @@ function TooltipRoot({
   } = contentProps ?? {};
 
   const tooltipNode = (
-    <BaseTooltip.Root
-      open={open}
-      defaultOpen={defaultOpen}
-      onOpenChange={onOpenChange}
-    >
+    <BaseTooltip.Root open={open} defaultOpen={defaultOpen} onOpenChange={onOpenChange}>
       <BaseTooltip.Trigger closeOnClick={closeOnClick} render={renderTrigger} />
       <BaseTooltip.Portal>
         <BaseTooltip.Positioner
@@ -144,7 +143,7 @@ function TooltipRoot({
           <BaseTooltip.Popup
             {...htmlProps}
             {...contentHtmlProps}
-            className={[styles.popup, className, contentClassName].filter(Boolean).join(' ')}
+            className={[styles.popup, className, contentClassName].filter(Boolean).join(" ")}
             style={{ ...(style ?? {}), ...(contentStyle ?? {}) }}
           >
             {content}
@@ -192,11 +191,7 @@ export function TooltipProvider({
 
   return (
     <TooltipProviderContext.Provider value={true}>
-      <BaseTooltip.Provider
-        delay={resolvedDelay}
-        closeDelay={closeDelay}
-        timeout={resolvedTimeout}
-      >
+      <BaseTooltip.Provider delay={resolvedDelay} closeDelay={closeDelay} timeout={resolvedTimeout}>
         {children}
       </BaseTooltip.Provider>
     </TooltipProviderContext.Provider>

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

@@ -1,22 +1,13 @@
 {
   "$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"
-  ],
+  "description": "Keeps text in the accessibility tree while taking it off the screen.",
+  "category": "utilities",
+  "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)"
-  ],
+  "propsSummary": ["children: node (required)", "as: span|div (default: span)"],
   "props": {
     "children": {
       "type": "node",
@@ -28,53 +19,45 @@
       "description": "HTML element to render",
       "default": "span",
       "required": false,
-      "values": [
-        "span",
-        "div"
-      ]
+      "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"
+      "An icon-only control needs a name",
+      "A link's text is vague out of context",
+      "A skip link needs to hide until focused"
     ],
     "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)"
+      "Nobody should see or hear it (render nothing)",
+      "The content is just collapsed (use aria-expanded)"
     ],
     "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"
+      "Every icon-only button gets one",
+      "Say the action, not the icon: \"Search\", not \"magnifier\"",
+      "Keep it short — it is read aloud",
+      "Visible text beats hidden text whenever there is room"
     ],
     "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"
+      "Screen readers announce it; the layout never moves",
+      "Focusable children inside still receive focus",
+      "Required for WCAG 2.1 on icon-only controls"
     ]
   },
   "examples": [
     {
       "name": "Icon Button Label",
-      "description": "Accessible label for icon-only button",
+      "description": "The only thing telling a screen reader what this button does.",
       "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",
+      "description": "Gives a vague link the context sighted readers get from layout.",
       "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",
+      "description": "Hidden until focused, then it jumps keyboard users past the nav.",
       "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>"
     }
   ],
@@ -96,16 +79,11 @@
       "as: span|div - HTML element",
       "Forwards standard DOM props (id, aria-*, data-*, className, handlers)"
     ],
-    "a11yRules": [
-      "A11Y_SR_ONLY",
-      "A11Y_ICON_LABEL"
-    ]
+    "a11yRules": ["A11Y_SR_ONLY", "A11Y_ICON_LABEL"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root"
-    ]
+    "subComponents": ["Root"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/VisuallyHidden/VisuallyHidden.module.scss

@@ -2,9 +2,12 @@
 // Based on the widely-used sr-only pattern
 .visuallyHidden {
   position: absolute;
+  /* fragments-allow FUI2004 reason="Accessibility clipping box must remain exactly one CSS pixel" expires="2027-08-01" */
   width: 1px;
+  /* fragments-allow FUI2004 reason="Accessibility clipping box must remain exactly one CSS pixel" expires="2027-08-01" */
   height: 1px;
   padding: 0;
+  /* fragments-allow FUI2004 reason="Negative offset keeps the clipping box outside visual layout" expires="2027-08-01" */
   margin: -1px;
   overflow: hidden;
   clip: rect(0, 0, 0, 0);

package/src/components/VisuallyHidden/index.tsx

@@ -1,10 +1,10 @@
-import * as React from 'react';
-import styles from './VisuallyHidden.module.scss';
+import * as React from "react";
+import styles from "./VisuallyHidden.module.scss";
 
 export interface VisuallyHiddenProps extends React.HTMLAttributes<HTMLElement> {
   children: React.ReactNode;
   /** HTML element to render */
-  as?: 'span' | 'div';
+  as?: "span" | "div";
 }
 
 /**
@@ -19,12 +19,12 @@ export interface VisuallyHiddenProps extends React.HTMLAttributes<HTMLElement> {
  * </Button>
  */
 const VisuallyHiddenRoot = React.forwardRef<HTMLElement, VisuallyHiddenProps>(
-  function VisuallyHidden({ children, as: Component = 'span', className, ...htmlProps }, ref) {
+  function VisuallyHidden({ children, as: Component = "span", className, ...htmlProps }, ref) {
     return (
       <Component
         ref={ref as React.Ref<never>}
         {...htmlProps}
-        className={[styles.visuallyHidden, className].filter(Boolean).join(' ')}
+        className={[styles.visuallyHidden, className].filter(Boolean).join(" ")}
       >
         {children}
       </Component>

package/src/index.ts

@@ -302,6 +302,7 @@ export {
   type FieldDescriptionProps,
   type FieldErrorProps,
   type FieldValidityProps,
+  type FieldRequiredProps,
 } from "./components/Field";
 
 // Fieldset
@@ -313,7 +314,7 @@ export {
 } from "./components/Fieldset";
 
 // Form
-export { Form, type FormProps } from "./components/Form";
+export { Form, type FormActionsProps, type FormProps } from "./components/Form";
 
 // Sidebar
 export {
@@ -677,8 +678,8 @@ export {
   usePrefersContrast,
   useFocusTrap,
   handleArrowNavigation,
-  VisuallyHidden as A11yVisuallyHidden,
-  type VisuallyHiddenProps as A11yVisuallyHiddenProps,
+  A11yVisuallyHidden,
+  type A11yVisuallyHiddenProps,
 } from "./utils/a11y";
 
 // Keyboard Shortcuts

package/src/measurements/MeasurementTargets.module.scss

@@ -0,0 +1,229 @@
+@use "../recipes/typography";
+@use "../tokens/measurements.generated" as measurements;
+@use "../tokens/variables" as tokens;
+
+.lineup {
+  display: grid;
+  gap: var(--fui-raw-space-24, #{measurements.raw-space("24")});
+  min-inline-size: 0;
+  padding: var(--fui-raw-space-24, #{measurements.raw-space("24")});
+  color: var(--fui-text-primary, #{tokens.$fui-text-primary});
+  background: var(--fui-bg-primary, #{tokens.$fui-bg-primary});
+}
+
+.header,
+.section,
+.specimenList,
+.specimenRow,
+.typographySpecimen {
+  display: grid;
+  min-inline-size: 0;
+}
+
+.header {
+  gap: var(--fui-raw-space-8, #{measurements.raw-space("8")});
+}
+
+.eyebrow,
+.specimenName {
+  @include typography.role("ui-compact");
+}
+
+.eyebrow {
+  margin: 0;
+  color: var(--fui-text-tertiary, #{tokens.$fui-text-tertiary});
+  text-transform: uppercase;
+}
+
+.title {
+  @include typography.role("title-lg");
+
+  margin: 0;
+}
+
+.description {
+  @include typography.role("body-compact");
+
+  margin: 0;
+  color: var(--fui-text-secondary, #{tokens.$fui-text-secondary});
+}
+
+.context {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--fui-raw-space-8, #{measurements.raw-space("8")});
+}
+
+.contextValue,
+.specimenValue {
+  @include typography.role("code");
+}
+
+.contextValue {
+  padding: var(--fui-raw-space-4, #{measurements.raw-space("4")})
+    var(--fui-raw-space-8, #{measurements.raw-space("8")});
+  border-radius: var(--fui-radius-sm, #{tokens.$fui-radius-sm});
+  color: var(--fui-text-secondary, #{tokens.$fui-text-secondary});
+  background: var(--fui-bg-tertiary, #{tokens.$fui-bg-tertiary});
+}
+
+.section {
+  gap: var(--fui-raw-space-16, #{measurements.raw-space("16")});
+  padding: var(--fui-raw-space-16, #{measurements.raw-space("16")});
+  border-radius: var(--fui-radius-lg, #{tokens.$fui-radius-lg});
+  background: var(--fui-bg-secondary, #{tokens.$fui-bg-secondary});
+  box-shadow: var(--fui-shadow-sm, #{tokens.$fui-shadow-sm});
+}
+
+.sectionTitle {
+  @include typography.role("title-sm");
+
+  margin: 0;
+}
+
+.specimenList {
+  gap: var(--fui-raw-space-12, #{measurements.raw-space("12")});
+}
+
+.specimenRow {
+  gap: var(--fui-raw-space-8, #{measurements.raw-space("8")});
+}
+
+.specimenMeta {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: var(--fui-raw-space-12, #{measurements.raw-space("12")});
+}
+
+.specimenName,
+.specimenValue {
+  margin: 0;
+}
+
+.specimenName {
+  color: var(--fui-text-secondary, #{tokens.$fui-text-secondary});
+}
+
+.specimenValue {
+  min-inline-size: 0;
+  overflow-wrap: anywhere;
+  color: var(--fui-text-tertiary, #{tokens.$fui-text-tertiary});
+}
+
+.controlTrack,
+.fieldTrack {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  min-inline-size: 0;
+  overflow: hidden;
+  white-space: nowrap;
+}
+
+.controlTrack {
+  @include typography.role("ui-compact");
+
+  inline-size: fit-content;
+  justify-content: center;
+  padding-inline: var(--fui-raw-space-12, #{measurements.raw-space("12")});
+  border-radius: var(--fui-radius-md, #{tokens.$fui-radius-md});
+  color: var(--fui-color-on-accent, #{tokens.$fui-color-on-accent});
+  background: var(--fui-color-accent, #{tokens.$fui-color-accent});
+}
+
+.controlTrackMicro {
+  block-size: var(--fui-control-track-micro, #{measurements.target-value("controlTrack", "micro")});
+}
+
+.controlTrackSm {
+  block-size: var(--fui-control-track-sm, #{measurements.target-value("controlTrack", "sm")});
+}
+
+.controlTrackMd {
+  block-size: var(--fui-control-track-md, #{measurements.target-value("controlTrack", "md")});
+}
+
+.controlTrackLg {
+  block-size: var(--fui-control-track-lg, #{measurements.target-value("controlTrack", "lg")});
+}
+
+.fieldTrack {
+  @include typography.role("ui-standard");
+
+  inline-size: 100%;
+  border-radius: var(--fui-radius-md, #{tokens.$fui-radius-md});
+  color: var(--fui-text-secondary, #{tokens.$fui-text-secondary});
+  background: var(--fui-bg-elevated, #{tokens.$fui-bg-elevated});
+}
+
+.fieldTrackSm {
+  block-size: var(--fui-field-track-sm, #{measurements.target-value("fieldTrack", "sm")});
+  padding-inline: var(
+    --fui-field-inline-inset-sm,
+    #{measurements.target-value("fieldInlineInset", "sm")}
+  );
+}
+
+.fieldTrackMd {
+  block-size: var(--fui-field-track-md, #{measurements.target-value("fieldTrack", "md")});
+  padding-inline: var(
+    --fui-field-inline-inset-md,
+    #{measurements.target-value("fieldInlineInset", "md")}
+  );
+}
+
+.fieldTrackLg {
+  block-size: var(--fui-field-track-lg, #{measurements.target-value("fieldTrack", "lg")});
+  padding-inline: var(
+    --fui-field-inline-inset-lg,
+    #{measurements.target-value("fieldInlineInset", "lg")}
+  );
+}
+
+.typographySpecimen {
+  gap: var(--fui-raw-space-4, #{measurements.raw-space("4")});
+  padding-block: var(--fui-raw-space-4, #{measurements.raw-space("4")});
+}
+
+.typographySample {
+  margin: 0;
+  overflow-wrap: anywhere;
+}
+
+.caption {
+  @include typography.role("caption");
+}
+
+.uiCompact {
+  @include typography.role("ui-compact");
+}
+
+.uiStandard {
+  @include typography.role("ui-standard");
+}
+
+.bodyCompact {
+  @include typography.role("body-compact");
+}
+
+.bodyRelaxed {
+  @include typography.role("body-relaxed");
+}
+
+.titleSm {
+  @include typography.role("title-sm");
+}
+
+.titleMd {
+  @include typography.role("title-md");
+}
+
+.titleLg {
+  @include typography.role("title-lg");
+}
+
+.code {
+  @include typography.role("code");
+}