@usefragments/ui 1.6.0 → 1.7.0

package/src/components/Dialog/index.tsx

@@ -1,8 +1,8 @@
-'use client';
+"use client";
 
-import * as React from 'react';
-import { Dialog as BaseDialog } from '@base-ui/react/dialog';
-import styles from './Dialog.module.scss';
+import * as React from "react";
+import { Dialog as BaseDialog } from "@base-ui/react/dialog";
+import styles from "./Dialog.module.scss";
 
 // ============================================
 // Types
@@ -30,17 +30,20 @@ export interface DialogContentProps extends React.HTMLAttributes<HTMLDivElement>
   /** Dialog width.
    * @default "md"
    * @see https://usefragments.com/components/dialog#sizes */
-  size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';
+  size?: "sm" | "md" | "lg" | "xl" | "full";
   /** Whether the dialog should autofocus content on open.
    * @default true */
   initialFocus?: boolean;
 }
 
-export interface DialogTitleProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
+export interface DialogTitleProps extends Omit<React.HTMLAttributes<HTMLElement>, "children"> {
   children: React.ReactNode;
 }
 
-export interface DialogDescriptionProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
+export interface DialogDescriptionProps extends Omit<
+  React.HTMLAttributes<HTMLElement>,
+  "children"
+> {
   children: React.ReactNode;
 }
 
@@ -61,7 +64,7 @@ type DialogTriggerAsButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement>
   asChild?: false;
 };
 
-type DialogTriggerAsChildProps = Omit<React.HTMLAttributes<HTMLElement>, 'children'> & {
+type DialogTriggerAsChildProps = Omit<React.HTMLAttributes<HTMLElement>, "children"> & {
   children: React.ReactElement;
   asChild: true;
 };
@@ -73,7 +76,7 @@ type DialogCloseAsButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> &
   asChild?: false;
 };
 
-type DialogCloseAsChildProps = Omit<React.HTMLAttributes<HTMLElement>, 'children'> & {
+type DialogCloseAsChildProps = Omit<React.HTMLAttributes<HTMLElement>, "children"> & {
   children: React.ReactElement;
   asChild: true;
 };
@@ -108,13 +111,7 @@ function CloseIcon() {
 // Components
 // ============================================
 
-function DialogRoot({
-  children,
-  open,
-  defaultOpen,
-  onOpenChange,
-  modal = true,
-}: DialogProps) {
+function DialogRoot({ children, open, defaultOpen, onOpenChange, modal = true }: DialogProps) {
   return (
     <BaseDialog.Root
       open={open}
@@ -127,15 +124,14 @@ function DialogRoot({
   );
 }
 
-function DialogTrigger({
-  children,
-  asChild,
-  className,
-  ...htmlProps
-}: DialogTriggerProps) {
+function DialogTrigger({ children, asChild, className, ...htmlProps }: DialogTriggerProps) {
   if (asChild) {
     return (
-      <BaseDialog.Trigger {...htmlProps} className={className} render={children as React.ReactElement}>
+      <BaseDialog.Trigger
+        {...htmlProps}
+        className={className}
+        render={children as React.ReactElement}
+      >
         {null}
       </BaseDialog.Trigger>
     );
@@ -150,14 +146,12 @@ function DialogTrigger({
 
 function DialogContent({
   children,
-  size = 'md',
+  size = "md",
   initialFocus = true,
   className,
   ...htmlProps
 }: DialogContentProps) {
-  const popupClasses = [styles.popup, styles[size], className]
-    .filter(Boolean)
-    .join(' ');
+  const popupClasses = [styles.popup, styles[size], className].filter(Boolean).join(" ");
 
   return (
     <BaseDialog.Portal>
@@ -172,17 +166,25 @@ function DialogContent({
 }
 
 function DialogHeader({ children, className, ...htmlProps }: DialogHeaderProps) {
-  const classes = [styles.header, className].filter(Boolean).join(' ');
-  return <div {...htmlProps} className={classes}>{children}</div>;
+  const classes = [styles.header, className].filter(Boolean).join(" ");
+  return (
+    <div {...htmlProps} className={classes}>
+      {children}
+    </div>
+  );
 }
 
 function DialogTitle({ children, className, ...htmlProps }: DialogTitleProps) {
-  const classes = [styles.title, className].filter(Boolean).join(' ');
-  return <BaseDialog.Title {...htmlProps} className={classes}>{children}</BaseDialog.Title>;
+  const classes = [styles.title, className].filter(Boolean).join(" ");
+  return (
+    <BaseDialog.Title {...htmlProps} className={classes}>
+      {children}
+    </BaseDialog.Title>
+  );
 }
 
 function DialogDescription({ children, className, ...htmlProps }: DialogDescriptionProps) {
-  const classes = [styles.description, className].filter(Boolean).join(' ');
+  const classes = [styles.description, className].filter(Boolean).join(" ");
   return (
     <BaseDialog.Description {...htmlProps} className={classes}>
       {children}
@@ -191,13 +193,21 @@ function DialogDescription({ children, className, ...htmlProps }: DialogDescript
 }
 
 function DialogBody({ children, className, ...htmlProps }: DialogBodyProps) {
-  const classes = [styles.body, className].filter(Boolean).join(' ');
-  return <div {...htmlProps} className={classes}>{children}</div>;
+  const classes = [styles.body, className].filter(Boolean).join(" ");
+  return (
+    <div {...htmlProps} className={classes}>
+      {children}
+    </div>
+  );
 }
 
 function DialogFooter({ children, className, ...htmlProps }: DialogFooterProps) {
-  const classes = [styles.footer, className].filter(Boolean).join(' ');
-  return <div {...htmlProps} className={classes}>{children}</div>;
+  const classes = [styles.footer, className].filter(Boolean).join(" ");
+  return (
+    <div {...htmlProps} className={classes}>
+      {children}
+    </div>
+  );
 }
 
 function DialogClose({ children, asChild, className, ...htmlProps }: DialogCloseProps) {
@@ -208,7 +218,7 @@ function DialogClose({ children, asChild, className, ...htmlProps }: DialogClose
         {...htmlProps}
         data-dialog-close
         aria-label="Close dialog"
-        className={[styles.close, className].filter(Boolean).join(' ')}
+        className={[styles.close, className].filter(Boolean).join(" ")}
       >
         <CloseIcon />
       </BaseDialog.Close>

package/src/components/Drawer/Drawer.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Drawer",
-  "description": "A panel that slides in from screen edges. Extends the Dialog pattern with slide animations and edge positioning.",
-  "category": "feedback",
-  "tags": [
-    "drawer",
-    "sheet",
-    "panel",
-    "sidebar",
-    "slide-over"
-  ],
+  "description": "Slides a panel in from a screen edge and dims the page behind it.",
+  "category": "overlays",
+  "tags": ["drawer", "sheet", "panel", "sidebar", "slide-over"],
   "status": "stable",
   "sourcePath": "src/components/Drawer/index.tsx",
   "exportName": "Drawer",
@@ -51,25 +45,23 @@
   },
   "usage": {
     "when": [
-      "Side panels for editing or creating content",
-      "Mobile-style bottom sheets for actions",
-      "Navigation panels that slide in from the left",
-      "Detail views that overlay the main content"
+      "Editing or creating alongside the page behind it",
+      "Touch-reachable action sheets",
+      "Navigation that slides in and back out",
+      "Detail views that overlay rather than replace"
     ],
     "whenNot": [
-      "Centered modal dialogs (use Dialog)",
-      "Non-blocking notifications (use Toast)",
-      "Permanent side navigation (use Sidebar)",
-      "Small contextual menus (use Menu or Popover)"
+      "A centred task (use Dialog)",
+      "Navigation that stays on screen (use Sidebar)",
+      "A short list of actions (use Menu or Popover)",
+      "Feedback the user does not act on (use Toast)"
     ],
     "guidelines": [
-      "Default to right side for content editing and forms",
-      "Use left side for navigation drawers",
-      "Use bottom for mobile-style action sheets",
-      "Provide clear close affordance (X button or cancel)",
-      "Keep drawer content focused on a single task",
-      "Drawer.Trigger and Drawer.Close with asChild require a single valid React element child",
-      "Set Drawer.Content initialFocus={false} when custom focus management is needed"
+      "Right for editing, left for navigation, bottom for touch",
+      "Always give the user a visible way out",
+      "One task per drawer",
+      "asChild on Trigger and Close needs a single element child",
+      "Set initialFocus={false} when you place focus yourself"
     ],
     "accessibility": [
       "Automatically traps focus within the drawer",
@@ -81,22 +73,22 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Right-side drawer with header, body, and footer",
+      "description": "Enters from the right, the default for editing and forms.",
       "code": "<Drawer>\n  <Drawer.Trigger asChild>\n    <Button>Open Drawer</Button>\n  </Drawer.Trigger>\n  <Drawer.Content>\n    <Drawer.Close />\n    <Drawer.Header>\n      <Drawer.Title>Drawer Title</Drawer.Title>\n      <Drawer.Description>\n        A panel sliding in from the right.\n      </Drawer.Description>\n    </Drawer.Header>\n    <Drawer.Body>\n      <p>Drawer content goes here.</p>\n    </Drawer.Body>\n    <Drawer.Footer>\n      <Drawer.Close asChild>\n        <Button variant=\"secondary\">Cancel</Button>\n      </Drawer.Close>\n      <Button variant=\"primary\">Save</Button>\n    </Drawer.Footer>\n  </Drawer.Content>\n</Drawer>"
     },
     {
       "name": "Left Side",
-      "description": "Left-side drawer for navigation",
+      "description": "Enters from the left, where navigation belongs.",
       "code": "<Drawer>\n  <Drawer.Trigger asChild>\n    <Button variant=\"secondary\">Open Left</Button>\n  </Drawer.Trigger>\n  <Drawer.Content side=\"left\">\n    <Drawer.Close />\n    <Drawer.Header>\n      <Drawer.Title>Navigation</Drawer.Title>\n    </Drawer.Header>\n    <Drawer.Body>\n      <p>Left-side drawer for navigation or filters.</p>\n    </Drawer.Body>\n  </Drawer.Content>\n</Drawer>"
     },
     {
       "name": "Bottom Sheet",
-      "description": "Bottom drawer for mobile-style actions",
+      "description": "Rises from the bottom for touch-reachable actions.",
       "code": "<Drawer>\n  <Drawer.Trigger asChild>\n    <Button variant=\"secondary\">Open Bottom Sheet</Button>\n  </Drawer.Trigger>\n  <Drawer.Content side=\"bottom\" size=\"sm\">\n    <Drawer.Header>\n      <Drawer.Title>Actions</Drawer.Title>\n    </Drawer.Header>\n    <Drawer.Body>\n      <p>Bottom sheet for mobile-style actions.</p>\n    </Drawer.Body>\n  </Drawer.Content>\n</Drawer>"
     },
     {
       "name": "With Form",
-      "description": "Drawer with a form layout",
+      "description": "Fields in the body, submit and cancel pinned to the footer.",
       "code": "<Drawer>\n  <Drawer.Trigger asChild>\n    <Button>Edit Settings</Button>\n  </Drawer.Trigger>\n  <Drawer.Content size=\"md\">\n    <Drawer.Close />\n    <Drawer.Header>\n      <Drawer.Title>Settings</Drawer.Title>\n      <Drawer.Description>Update your preferences.</Drawer.Description>\n    </Drawer.Header>\n    <Drawer.Body>\n      <Stack gap=\"md\">\n        <Input label=\"Display Name\" placeholder=\"Enter name\" />\n        <Input label=\"Email\" type=\"email\" placeholder=\"you@example.com\" />\n      </Stack>\n    </Drawer.Body>\n    <Drawer.Footer>\n      <Drawer.Close asChild>\n        <Button variant=\"secondary\">Cancel</Button>\n      </Drawer.Close>\n      <Button variant=\"primary\">Save Changes</Button>\n    </Drawer.Footer>\n  </Drawer.Content>\n</Drawer>"
     }
   ],
@@ -126,11 +118,7 @@
       "Drawer.Content size: sm|md|lg|xl|full - panel size",
       "Drawer.Content initialFocus: boolean - auto-focus popup on open (default: true)"
     ],
-    "a11yRules": [
-      "A11Y_DIALOG_FOCUS",
-      "A11Y_DIALOG_ESCAPE",
-      "A11Y_DIALOG_LABEL"
-    ]
+    "a11yRules": ["A11Y_DIALOG_FOCUS", "A11Y_DIALOG_ESCAPE", "A11Y_DIALOG_LABEL"]
   },
   "ai": {
     "compositionPattern": "compound",
@@ -145,9 +133,7 @@
       "Body",
       "Footer"
     ],
-    "requiredChildren": [
-      "Content"
-    ],
+    "requiredChildren": ["Content"],
     "commonPatterns": [
       "<Drawer><Drawer.Trigger><Button>Open</Button></Drawer.Trigger><Drawer.Content><Drawer.Close /><Drawer.Header><Drawer.Title>{title}</Drawer.Title></Drawer.Header><Drawer.Body>{content}</Drawer.Body><Drawer.Footer><Drawer.Close asChild><Button variant=\"secondary\">Cancel</Button></Drawer.Close><Button>Save</Button></Drawer.Footer></Drawer.Content></Drawer>"
     ]

package/src/components/Editor/Editor.contract.json

@@ -1,17 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Editor",
-  "description": "Rich text editor with formatting toolbar, auto-save, and word count",
-  "category": "forms",
-  "tags": [
-    "editor",
-    "rich-text",
-    "markdown",
-    "toolbar",
-    "writing",
-    "blog",
-    "content"
-  ],
+  "description": "Edits rich text with formatting, autosave, and a word count.",
+  "category": "inputs",
+  "tags": ["editor", "rich-text", "markdown", "toolbar", "writing", "blog", "content"],
   "status": "stable",
   "dependencies": [
     {
@@ -123,11 +115,7 @@
       "description": "Editor size preset: \"sm\" (120px), \"md\" (200px), or \"lg\" (400px)",
       "default": "md",
       "required": false,
-      "values": [
-        "sm",
-        "md",
-        "lg"
-      ]
+      "values": ["sm", "md", "lg"]
     },
     "maxLength": {
       "type": "number",
@@ -142,27 +130,26 @@
   },
   "usage": {
     "when": [
-      "Building blog post or article editors",
-      "Need rich text editing with formatting controls",
-      "Content management with auto-save and word count",
-      "Markdown or WYSIWYG editing interfaces"
+      "Blog posts and long-form articles",
+      "Text that needs formatting controls beside it",
+      "Drafts that autosave and report a word count",
+      "Markdown or WYSIWYG authoring"
     ],
     "whenNot": [
-      "Simple single-line text input (use Input)",
-      "Plain multi-line without formatting (use Textarea)",
-      "Chat/AI prompt input (use Prompt)",
+      "Single-line text (use Input)",
+      "Multi-line with no formatting (use Textarea)",
+      "Chat or AI prompt input (use Prompt)",
       "Code editing (use CodeBlock)"
     ],
     "guidelines": [
-      "Use compound pattern for custom toolbar layouts",
-      "Install @tiptap/react, @tiptap/starter-kit, and @tiptap/extension-link for rich text mode",
-      "Falls back to a markdown-aware textarea when TipTap is not installed",
-      "Use onAutoSave for periodic content persistence",
-      "onAutoSave may return a Promise; save status updates after the async save resolves/rejects",
-      "Use size prop (sm/md/lg) to control editor height",
-      "Use maxLength to show character limit with visual warning states",
-      "New formats (headings, blockquote, orderedList, undo, redo) are opt-in via the formats prop",
-      "Use toolbarIcons to swap in icons from any icon package without changing toolbar button labels or accessibility behavior"
+      "Compose Editor.Toolbar and Editor.Content to control toolbar layout",
+      "Rich text needs @tiptap/react, @tiptap/starter-kit, and @tiptap/extension-link",
+      "Without TipTap it falls back to a markdown-aware textarea",
+      "onAutoSave may return a Promise; save status updates once it settles",
+      "size sets the minimum body height: sm 120px, md 200px, lg 400px",
+      "maxLength drives the counter's warning and over-limit states",
+      "Headings, blockquote, orderedList, undo, and redo are opt-in via formats",
+      "toolbarIcons swaps glyphs without changing labels or keyboard behavior"
     ],
     "accessibility": [
       "Toolbar has role=\"toolbar\" with aria-label",
@@ -177,47 +164,47 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Editor with default toolbar and status bar",
+      "description": "Toolbar and status bar you get with no configuration.",
       "code": "<Editor placeholder=\"Start typing your masterpiece here...\" />"
     },
     {
       "name": "With Auto-Save and Publish",
-      "description": "Full compound usage with custom toolbar, auto-save indicator, and publish button",
+      "description": "Save state sits next to the primary action in the toolbar.",
       "code": "<Editor\n  placeholder=\"Start typing your masterpiece here...\"\n  onValueChange={(v) => console.log(v)}\n>\n  <Editor.Toolbar>\n    <Editor.ToolbarGroup aria-label=\"Text formatting\">\n      <Editor.ToolbarButton format=\"bold\" />\n      <Editor.ToolbarButton format=\"italic\" />\n      <Editor.ToolbarButton format=\"strikethrough\" />\n      <Editor.ToolbarButton format=\"link\" />\n      <Editor.ToolbarButton format=\"code\" />\n      <Editor.ToolbarButton format=\"bulletList\" />\n    </Editor.ToolbarGroup>\n    <Editor.ToolbarGroup aria-label=\"Actions\">\n      <Editor.StatusIndicator status=\"saved\" />\n      <Button variant=\"accent\" size=\"sm\">\n        Publish\n      </Button>\n    </Editor.ToolbarGroup>\n  </Editor.Toolbar>\n  <Editor.Content />\n  <Editor.StatusBar showWordCount showCharCount />\n</Editor>"
     },
     {
-      "name": "Minimal",
-      "description": "Editor with subset of formats",
-      "code": "<Editor\n  placeholder=\"Quick note...\"\n  formats={['bold', 'italic', 'code']}\n/>"
+      "name": "Save Failed",
+      "description": "A failed autosave turns the status text red.",
+      "code": "<Editor defaultValue=\"This draft could not be saved.\">\n  <Editor.Toolbar>\n    <Editor.ToolbarGroup aria-label=\"Text formatting\">\n      <Editor.ToolbarButton format=\"bold\" />\n      <Editor.ToolbarButton format=\"italic\" />\n    </Editor.ToolbarGroup>\n    <Editor.ToolbarGroup aria-label=\"Status\">\n      <Editor.StatusIndicator status=\"error\" />\n    </Editor.ToolbarGroup>\n  </Editor.Toolbar>\n  <Editor.Content />\n  <Editor.StatusBar showWordCount showCharCount />\n</Editor>"
     },
     {
       "name": "Disabled",
-      "description": "Non-interactive editor with content",
+      "description": "Dimmed and inert, but the text stays readable.",
       "code": "<Editor\n  defaultValue=\"This content cannot be edited.\"\n  disabled\n/>"
     },
     {
       "name": "Read Only",
-      "description": "Visible content, non-editable",
+      "description": "Text can be selected and copied, but never changed.",
       "code": "<Editor\n  defaultValue=\"This content is read-only. You can select and copy text but cannot modify it.\"\n  readOnly\n/>"
     },
     {
       "name": "Custom Toolbar",
-      "description": "Compound usage with custom toolbar layout and separator",
+      "description": "Separators split the controls into labelled clusters.",
       "code": "<Editor\n  placeholder=\"Write your blog post...\"\n  onValueChange={(v) => console.log(v)}\n>\n  <Editor.Toolbar>\n    <Editor.ToolbarGroup aria-label=\"Basic formatting\">\n      <Editor.ToolbarButton format=\"bold\" />\n      <Editor.ToolbarButton format=\"italic\" />\n    </Editor.ToolbarGroup>\n    <Editor.Separator />\n    <Editor.ToolbarGroup aria-label=\"Advanced formatting\">\n      <Editor.ToolbarButton format=\"link\" />\n      <Editor.ToolbarButton format=\"code\" />\n      <Editor.ToolbarButton format=\"bulletList\" />\n    </Editor.ToolbarGroup>\n    <Editor.ToolbarGroup aria-label=\"Status\">\n      <Editor.StatusIndicator status=\"saving\" />\n    </Editor.ToolbarGroup>\n  </Editor.Toolbar>\n  <Editor.Content />\n  <Editor.StatusBar showWordCount showCharCount />\n</Editor>"
     },
     {
       "name": "Full Formatting",
-      "description": "All format options including headings, blockquote, ordered list, undo/redo",
+      "description": "Every opt-in format switched on, at the tallest preset.",
       "code": "<Editor\n  placeholder=\"Write an article...\"\n  size=\"lg\"\n>\n  <Editor.Toolbar>\n    <Editor.ToolbarGroup aria-label=\"History\">\n      <Editor.ToolbarButton format=\"undo\" />\n      <Editor.ToolbarButton format=\"redo\" />\n    </Editor.ToolbarGroup>\n    <Editor.Separator />\n    <Editor.ToolbarGroup aria-label=\"Headings\">\n      <Editor.ToolbarButton format=\"heading1\" />\n      <Editor.ToolbarButton format=\"heading2\" />\n      <Editor.ToolbarButton format=\"heading3\" />\n    </Editor.ToolbarGroup>\n    <Editor.Separator />\n    <Editor.ToolbarGroup aria-label=\"Text formatting\">\n      <Editor.ToolbarButton format=\"bold\" />\n      <Editor.ToolbarButton format=\"italic\" />\n      <Editor.ToolbarButton format=\"strikethrough\" />\n      <Editor.ToolbarButton format=\"code\" />\n    </Editor.ToolbarGroup>\n    <Editor.Separator />\n    <Editor.ToolbarGroup aria-label=\"Block formatting\">\n      <Editor.ToolbarButton format=\"bulletList\" />\n      <Editor.ToolbarButton format=\"orderedList\" />\n      <Editor.ToolbarButton format=\"blockquote\" />\n      <Editor.ToolbarButton format=\"link\" />\n    </Editor.ToolbarGroup>\n  </Editor.Toolbar>\n  <Editor.Content />\n  <Editor.StatusBar showWordCount showCharCount />\n</Editor>"
     },
     {
       "name": "With Character Limit",
-      "description": "Editor with maxLength showing character count indicator with warning and error states",
+      "description": "The counter warns near 280 characters and turns red past it.",
       "code": "<Editor\n  placeholder=\"Write a tweet-sized message...\"\n  maxLength={280}\n  size=\"sm\"\n  formats={['bold', 'italic', 'link']}\n/>"
     },
     {
       "name": "Small Size",
-      "description": "Compact editor with sm size preset (120px min-height)",
+      "description": "A 120px body with a trimmed toolbar, for tight spaces.",
       "code": "<Editor\n  placeholder=\"Quick note...\"\n  size=\"sm\"\n  formats={['bold', 'italic', 'code']}\n/>"
     }
   ],
@@ -253,11 +240,7 @@
       "maxLength: number - character limit with visual indicator",
       "toolbarIcons: Partial<Record<EditorFormat, ReactNode | (state) => ReactNode>> - custom toolbar icons"
     ],
-    "a11yRules": [
-      "A11Y_TOOLBAR_ROLE",
-      "A11Y_BUTTON_LABEL",
-      "A11Y_LIVE_REGION"
-    ]
+    "a11yRules": ["A11Y_TOOLBAR_ROLE", "A11Y_BUTTON_LABEL", "A11Y_LIVE_REGION"]
   },
   "ai": {
     "compositionPattern": "compound",

package/src/components/Editor/Editor.module.scss

@@ -9,6 +9,8 @@
 .editor {
   @include form-group-surface;
 
+  // Component-scoped registered vocabulary: these are declared here as the
+  // token source for the editor's size presets, not ad-hoc custom properties.
   --fui-editor-min-block-sm: 120px;
   --fui-editor-min-block-md: 200px;
   --fui-editor-min-block-lg: 400px;
@@ -60,7 +62,7 @@
 }
 
 .toolbar {
-  border-block-end: var(--fui-stroke-hairline) solid var(--fui-form-group-border, $fui-border);
+  border-block-end: var(--fui-stroke-hairline, 1px) solid var(--fui-form-group-border, $fui-border);
 }
 
 .toolbarGroup,
@@ -77,7 +79,7 @@
   @include action.icon-only("sm");
   @include target.hit-area("compact");
 
-  border: var(--fui-stroke-hairline) solid transparent;
+  border: var(--fui-stroke-hairline, 1px) solid transparent;
   border-radius: var(--fui-radius-sm, $fui-radius-sm);
   background-color: transparent;
   color: var(--fui-text-secondary, $fui-text-secondary);
@@ -94,6 +96,10 @@
     background-color: var(--fui-field-selection-bg, $fui-bg-hover);
   }
 
+  &:focus-visible {
+    @include focus-ring;
+  }
+
   &:disabled {
     cursor: not-allowed;
   }
@@ -107,13 +113,13 @@
   border-color: var(--fui-field-selection-border, $fui-color-accent);
   background-color: var(--fui-field-selection-bg, $fui-bg-hover);
   color: var(--fui-text-primary, $fui-text-primary);
-  box-shadow: inset 0 0 0 var(--fui-stroke-hairline)
+  box-shadow: inset 0 0 0 var(--fui-stroke-hairline, 1px)
     color-mix(in srgb, var(--fui-field-selection-border, $fui-color-accent) 55%, transparent);
 }
 
 .separator {
-  inline-size: var(--fui-stroke-hairline);
-  block-size: var(--fui-icon-md);
+  inline-size: var(--fui-stroke-hairline, 1px);
+  block-size: var(--fui-icon-md, $fui-icon-md);
   margin-inline: layout.gap("xs");
   background-color: var(--fui-form-group-border, $fui-border);
   flex-shrink: 0;
@@ -161,14 +167,6 @@
     @include prose.paragraph;
   }
 
-  p.is-editor-empty:first-child::before {
-    content: attr(data-placeholder);
-    float: inline-start;
-    block-size: 0;
-    color: var(--fui-text-tertiary, $fui-text-tertiary);
-    pointer-events: none;
-  }
-
   @for $level from 1 through 6 {
     h#{$level} {
       @include prose.heading($level);
@@ -206,10 +204,33 @@
   }
 }
 
+// TipTap's Placeholder extension is not a dependency, so the empty-document
+// placeholder is driven from the wrapper's own data-placeholder attribute.
+// An empty ProseMirror doc is exactly one paragraph holding a trailing break.
+.contentRich[data-placeholder]:has(
+    :global(.tiptap) > p:only-child > br:global(.ProseMirror-trailingBreak)
+  ) {
+  position: relative;
+
+  &::before {
+    @include typography.role("body-relaxed");
+
+    content: attr(data-placeholder);
+    position: absolute;
+    inset-block-start: layout.gap("lg");
+    inset-inline-start: layout.gap("lg");
+    inset-inline-end: layout.gap("lg");
+    color: var(--fui-text-tertiary, $fui-text-tertiary);
+    pointer-events: none;
+  }
+}
+
 .contentTextarea {
   @include button-reset;
   @include typography.role("body-relaxed");
 
+  // button-reset marks pressables select-none; typed text must stay selectable.
+  user-select: text;
   display: block;
   inline-size: 100%;
   block-size: 100%;
@@ -234,7 +255,8 @@
 }
 
 .statusBar {
-  border-block-start: var(--fui-stroke-hairline) solid var(--fui-form-group-border, $fui-border);
+  border-block-start: var(--fui-stroke-hairline, 1px) solid
+    var(--fui-form-group-border, $fui-border);
   background-color: color-mix(
     in srgb,
     var(--fui-form-group-bg, $fui-bg-secondary) 56%,