@usefragments/ui 1.0.0

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

@@ -0,0 +1,263 @@
+{
+  "$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"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Editor/index.tsx",
+  "exportName": "Editor",
+  "propsSummary": [
+    "children: node",
+    "value: string",
+    "defaultValue: string (default: )",
+    "onValueChange: function",
+    "placeholder: string (default: Start typing...)",
+    "disabled: boolean (default: false)",
+    "readOnly: boolean (default: false)",
+    "formats: array",
+    "toolbar: boolean (default: true)",
+    "statusBar: boolean (default: true)",
+    "onAutoSave: function",
+    "autoSaveInterval: number (default: 30000)",
+    "size: sm|md|lg (default: md)",
+    "maxLength: number",
+    "toolbarIcons: object"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "",
+      "required": false
+    },
+    "value": {
+      "type": "string",
+      "description": "Controlled editor value",
+      "required": false
+    },
+    "defaultValue": {
+      "type": "string",
+      "description": "Default value for uncontrolled usage",
+      "default": "",
+      "required": false
+    },
+    "onValueChange": {
+      "type": "function",
+      "description": "Called when content changes",
+      "required": false
+    },
+    "placeholder": {
+      "type": "string",
+      "description": "Placeholder text shown when empty",
+      "default": "Start typing...",
+      "required": false
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Disable the editor",
+      "default": "false",
+      "required": false
+    },
+    "readOnly": {
+      "type": "boolean",
+      "description": "Make the editor read-only",
+      "default": "false",
+      "required": false
+    },
+    "formats": {
+      "type": "array",
+      "description": "Which format buttons to show in the toolbar",
+      "default": "[\"bold\", \"italic\", \"strikethrough\", \"link\", \"code\", \"bulletList\"]",
+      "required": false
+    },
+    "toolbar": {
+      "type": "boolean",
+      "description": "Show default toolbar",
+      "default": "true",
+      "required": false
+    },
+    "statusBar": {
+      "type": "boolean",
+      "description": "Show default status bar with word/character counts",
+      "default": "true",
+      "required": false
+    },
+    "onAutoSave": {
+      "type": "function",
+      "description": "Auto-save callback, called at autoSaveInterval (may be async)",
+      "required": false
+    },
+    "autoSaveInterval": {
+      "type": "number",
+      "description": "Auto-save interval in milliseconds",
+      "default": "30000",
+      "required": false
+    },
+    "size": {
+      "type": "enum",
+      "description": "Editor size preset: \"sm\" (120px), \"md\" (200px), or \"lg\" (400px)",
+      "default": "md",
+      "required": false,
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "maxLength": {
+      "type": "number",
+      "description": "Maximum character count. Shows counter in status bar with warning (90%) and error (over limit) states",
+      "required": false
+    },
+    "toolbarIcons": {
+      "type": "object",
+      "description": "Optional toolbar icon overrides keyed by format/action (e.g. bold, italic, undo). Values can be React nodes or render functions.",
+      "required": false
+    }
+  },
+  "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"
+    ],
+    "whenNot": [
+      "Simple single-line text input (use Input)",
+      "Plain multi-line without formatting (use Textarea)",
+      "Chat/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"
+    ],
+    "accessibility": [
+      "Toolbar has role=\"toolbar\" with aria-label",
+      "Format buttons use aria-pressed to indicate active state",
+      "Action buttons (undo/redo) omit aria-pressed since they are not toggles",
+      "Status indicator uses aria-live=\"polite\" for save status announcements",
+      "Keyboard shortcuts match standard text editor conventions (Ctrl+B, Ctrl+I, etc.)",
+      "Global shortcuts (e.g., Sidebar Ctrl+B) automatically yield when focus is inside the Editor",
+      "Focus ring appears on the editor container when any child element is focused"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Editor with default toolbar and status bar",
+      "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",
+      "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": "Disabled",
+      "description": "Non-interactive editor with content",
+      "code": "<Editor\n  defaultValue=\"This content cannot be edited.\"\n  disabled\n/>"
+    },
+    {
+      "name": "Read Only",
+      "description": "Visible content, non-editable",
+      "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",
+      "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",
+      "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",
+      "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)",
+      "code": "<Editor\n  placeholder=\"Quick note...\"\n  size=\"sm\"\n  formats={['bold', 'italic', 'code']}\n/>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Prompt",
+      "relationship": "sibling",
+      "note": "Prompt is for AI/chat input; Editor is for long-form content editing"
+    },
+    {
+      "component": "Textarea",
+      "relationship": "alternative",
+      "note": "Use Textarea for simple multi-line input without formatting toolbar"
+    },
+    {
+      "component": "Input",
+      "relationship": "alternative",
+      "note": "Use Input for single-line text input"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "value: string - controlled editor value",
+      "onValueChange: (value: string) => void - change callback",
+      "placeholder: string - hint text (default: \"Start typing...\")",
+      "disabled: boolean - disables interaction",
+      "readOnly: boolean - prevents editing",
+      "formats: EditorFormat[] - toolbar buttons (default: all 6)",
+      "toolbar: boolean - show default toolbar (default: true)",
+      "statusBar: boolean - show word/char counts (default: true)",
+      "onAutoSave: (value: string) => void | Promise<void> - auto-save handler",
+      "size: \"sm\" | \"md\" | \"lg\" - editor height preset (default: \"md\")",
+      "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"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Toolbar",
+      "ToolbarGroup",
+      "ToolbarButton",
+      "Separator",
+      "StatusIndicator",
+      "Content",
+      "StatusBar"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:56.748Z"
+  }
+}

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

@@ -0,0 +1,352 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+
+// ============================================
+// Editor Root
+// ============================================
+
+.editor {
+  @include form-group-surface;
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  min-width: 0;
+  overflow: hidden;
+
+  // Focus ring (Enhancement #7)
+  &:focus-within:not([data-disabled]) {
+    @include focus-ring;
+  }
+
+  &[data-disabled] {
+    opacity: 0.5;
+    pointer-events: none;
+  }
+
+  &[data-readonly] {
+    .contentTextarea {
+      cursor: default;
+    }
+  }
+
+  // Size variants (Enhancement #2)
+  &[data-size="sm"] {
+    .content,
+    .contentTextarea,
+    :global(.tiptap) {
+      min-height: 120px;
+    }
+  }
+
+  &[data-size="md"] {
+    .content,
+    .contentTextarea,
+    :global(.tiptap) {
+      min-height: 200px;
+    }
+  }
+
+  &[data-size="lg"] {
+    .content,
+    .contentTextarea,
+    :global(.tiptap) {
+      min-height: 400px;
+    }
+  }
+}
+
+// ============================================
+// Toolbar
+// ============================================
+
+.toolbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  flex-wrap: wrap;
+  gap: var(--fui-space-2, $fui-space-2);
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-2, $fui-space-2);
+  border-bottom: 1px solid var(--fui-form-group-border, $fui-border);
+  background-color: color-mix(
+    in srgb,
+    var(--fui-form-group-bg, $fui-bg-secondary) 72%,
+    transparent
+  );
+}
+
+// ============================================
+// Toolbar Group
+// ============================================
+
+.toolbarGroup {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-0-5, $fui-space-0-5);
+}
+
+// ============================================
+// Toolbar Button
+// ============================================
+
+.toolbarButton {
+  @include button-reset;
+  @include interactive-base;
+  @include touch-target;
+
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: var(--fui-button-height-sm, $fui-button-height-sm);
+  min-height: var(--fui-button-height-sm, $fui-button-height-sm);
+  padding: 0;
+  border: 1px solid transparent;
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  background-color: transparent;
+  color: var(--fui-text-secondary, $fui-text-secondary);
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-field-bg, $fui-bg-elevated);
+    border-color: var(--fui-form-group-border, $fui-border);
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  &:active:not(:disabled) {
+    background-color: var(--fui-field-selection-bg, $fui-bg-hover);
+    border-color: var(--fui-field-selection-border, $fui-color-accent);
+  }
+
+  svg {
+    width: var(--fui-icon-sm, $fui-icon-sm); // 14px
+    height: var(--fui-icon-sm, $fui-icon-sm);
+  }
+}
+
+.toolbarButtonActive {
+  color: var(--fui-text-primary, $fui-text-primary);
+  background-color: var(--fui-field-selection-bg, $fui-bg-hover);
+  border-color: var(--fui-field-selection-border, $fui-color-accent);
+  box-shadow: inset 0 0 0 1px
+    color-mix(in srgb, var(--fui-field-selection-border, $fui-color-accent) 55%, transparent);
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-field-selection-bg-hover, $fui-bg-hover);
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+}
+
+// ============================================
+// Separator
+// ============================================
+
+.separator {
+  width: 1px;
+  height: 1rem;
+  background-color: var(--fui-form-group-border, $fui-border);
+  margin: 0 var(--fui-space-1, $fui-space-1);
+  flex-shrink: 0;
+}
+
+// ============================================
+// Status Indicator
+// ============================================
+
+.statusIndicator {
+  @include section-label-text;
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+  white-space: nowrap;
+  padding: 0 var(--fui-space-2, $fui-space-2);
+}
+
+.statusError {
+  color: var(--fui-color-danger-text, $fui-color-danger-text);
+}
+
+// ============================================
+// Content
+// ============================================
+
+.content {
+  flex: 1;
+  min-height: 200px;
+  overflow-y: auto;
+}
+
+.contentRich {
+  // TipTap editor styling
+  :global(.tiptap) {
+    padding: var(--fui-space-3, $fui-space-3);
+    min-height: 200px;
+    outline: none;
+    @include text-base;
+    line-height: var(--fui-line-height-relaxed, $fui-line-height-relaxed);
+    font-size: var(--fui-font-size-base, $fui-font-size-base);
+
+    &:focus-visible {
+      outline: none;
+    }
+
+    // Placeholder
+    p.is-editor-empty:first-child::before {
+      content: attr(data-placeholder);
+      float: left;
+      color: var(--fui-text-tertiary, $fui-text-tertiary);
+      pointer-events: none;
+      height: 0;
+    }
+
+    // Headings (Enhancement #4)
+    // Heading scale matches Markdown's prose scale (h1=3xl, h2=xl, h3=lg) so the
+    // editing canvas mirrors how the rendered content reads.
+    h1 {
+      font-size: var(--fui-font-size-3xl, $fui-font-size-3xl);
+      font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
+      line-height: var(--fui-line-height-tight, $fui-line-height-tight);
+      margin: 0 0 var(--fui-space-3, $fui-space-3);
+    }
+
+    h2 {
+      font-size: var(--fui-font-size-xl, $fui-font-size-xl);
+      font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
+      line-height: var(--fui-line-height-tight, $fui-line-height-tight);
+      margin: 0 0 var(--fui-space-2, $fui-space-2);
+    }
+
+    h3 {
+      font-size: var(--fui-font-size-lg, $fui-font-size-lg);
+      font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
+      line-height: var(--fui-line-height-tight, $fui-line-height-tight);
+      margin: 0 0 var(--fui-space-2, $fui-space-2);
+    }
+
+    // Blockquote (Enhancement #5)
+    blockquote {
+      border-left: 3px solid var(--fui-color-accent, $fui-color-accent);
+      padding-left: var(--fui-space-4, $fui-space-4);
+      margin: 0 0 var(--fui-space-2, $fui-space-2);
+      color: var(--fui-text-secondary, $fui-text-secondary);
+      font-style: italic;
+    }
+
+    // Inline code — padding matches Markdown's inline <code> (0.125em 0.375em)
+    code {
+      background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+      border-radius: var(--fui-radius-sm, $fui-radius-sm);
+      padding: 0.125em 0.375em;
+      font-family: var(--fui-font-mono, $fui-font-mono);
+      font-size: 0.9em;
+    }
+
+    // Links
+    a {
+      color: var(--fui-color-accent, $fui-color-accent);
+      text-decoration: underline;
+      cursor: pointer;
+
+      &:hover {
+        color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+      }
+    }
+
+    // Unordered lists
+    ul {
+      padding-left: var(--fui-space-5, $fui-space-5);
+      list-style-type: disc;
+    }
+
+    // Ordered lists (Enhancement #3)
+    ol {
+      padding-left: var(--fui-space-5, $fui-space-5);
+      list-style-type: decimal;
+    }
+
+    // Strikethrough
+    s {
+      text-decoration: line-through;
+    }
+
+    // Paragraphs
+    p {
+      margin: 0 0 var(--fui-space-2, $fui-space-2);
+
+      &:last-child {
+        margin-bottom: 0;
+      }
+    }
+  }
+}
+
+.contentTextarea {
+  @include button-reset;
+  @include text-base;
+
+  display: block;
+  width: 100%;
+  height: 100%;
+  min-height: 200px;
+  padding: var(--fui-space-3, $fui-space-3);
+  background: transparent;
+  border: none;
+  resize: none;
+  overflow-y: auto;
+  line-height: var(--fui-line-height-relaxed, $fui-line-height-relaxed);
+  font-size: var(--fui-font-size-base, $fui-font-size-base);
+
+  &::placeholder {
+    color: var(--fui-text-tertiary, $fui-text-tertiary);
+  }
+
+  &:focus-visible {
+    outline: none;
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+  }
+}
+
+// ============================================
+// Status Bar
+// ============================================
+
+.statusBar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--fui-space-2, $fui-space-2);
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-2, $fui-space-2);
+  border-top: 1px solid var(--fui-form-group-border, $fui-border);
+  background-color: color-mix(
+    in srgb,
+    var(--fui-form-group-bg, $fui-bg-secondary) 56%,
+    transparent
+  );
+}
+
+.statusBarLeft {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-2, $fui-space-2);
+}
+
+.statusBarRight {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-2, $fui-space-2);
+  margin-left: auto;
+}
+
+.statusBarItem {
+  @include helper-text;
+  white-space: nowrap;
+}
+
+// maxLength indicator states (Enhancement #1)
+.statusBarItemWarning {
+  color: var(--fui-color-warning-text, $fui-color-warning-text);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+}
+
+.statusBarItemError {
+  color: var(--fui-color-danger-text, $fui-color-danger-text);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+}