@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/RichText/RichTextAttachment.module.scss

@@ -0,0 +1,82 @@
+// Attachment body styles, moved out of RichTextEditor.module.scss (#509).
+// RichTextAttachment renders inside the READ-ONLY viewer as well as the editor
+// — renderDoc calls it — so it belongs to the lower of the two layers. Living in
+// the editor's stylesheet was the same inversion as the import that created the
+// dependency cycle.
+// The `.root` / `.shell` scoped `figure[data-attachment]` rules stay in
+// RichTextEditor.module.scss — those describe the editor's chrome. The GLOBAL
+// `data-align` rules below came with the move: they are not editor-scoped, and
+// the read-only viewer reached them only because RichTextAttachment used to
+// import the editor's stylesheet. With that import gone, a consumer rendering
+// <RichText> without ever mounting <RichTextEditor> would have lost centre and
+// right alignment entirely — the editor's stylesheet is tree-shakeable along
+// with the component.
+
+// The attachment image preview. `inline-block` lets the figure's `text-align`
+// (data-align) position it (left/center/right); `width` attr + `height: auto`
+// render the configured display size at natural aspect; `max-width: 100%` keeps a
+// wide image from overflowing (Rule 4: 100% allowed).
+// Height cap (#644): render-time only, stored width/height untouched. The width
+// shrinks to `cap × aspect` (aspect published by RichTextAttachment on load) so the
+// ratio holds; until then (or with no aspect) `max-height` alone bounds it. The
+// cap is overridable per instance via the `imageMaxHeight` prop, which sets
+// `--rich-text-image-max-height` on the RichText / RichTextEditor root.
+.attachmentImg {
+  --rich-text-image-cap: var(--rich-text-image-max-height, var(--size-rich-text-image-max-height));
+
+  display: inline-block;
+  max-width: min(100%, calc(var(--rich-text-image-cap) * var(--rich-text-image-aspect, 1000)));
+  max-height: var(--rich-text-image-cap);
+  height: auto;
+}
+
+.attachmentLoading,
+.attachmentError {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-1) var(--space-2);
+  border: var(--border-width) solid var(--color-border);
+  border-radius: var(--radius-md);
+  background: var(--color-bg-muted);
+  color: var(--color-fg-muted);
+}
+
+.attachmentChip {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-1);
+  padding: var(--space-1) var(--space-2);
+  border: var(--border-width) solid var(--color-border);
+  border-radius: var(--radius-md);
+  background: var(--color-bg);
+  color: var(--color-fg);
+  text-decoration: none;
+}
+
+.attachmentName {
+  font-weight: var(--font-weight-medium);
+}
+
+.attachmentLabel {
+  color: var(--color-danger);
+}
+
+.attachmentReason {
+  color: var(--color-fg);
+}
+
+// Image alignment within the attachment figure. `text-align` aligns the inline
+// <img> child — an allowed property (not the forbidden margin/position/flex/width).
+// These are intentionally GLOBAL (attribute selectors, not CSS-module classes):
+// `data-align` is a DOM attribute set by renderDoc, and the rules must apply in
+// BOTH the editor and the read-only `<RichText>` viewer, which render the same
+// `figure[data-attachment]` markup. Scoped only to aligned figures so the
+// (unaligned) spinner/error/chip states keep their own inline-flex layout.
+figure[data-attachment][data-align='center'] {
+  text-align: center;
+}
+
+figure[data-attachment][data-align='right'] {
+  text-align: right;
+}

package/src/components/RichText/RichTextAttachment.tsx

@@ -0,0 +1,122 @@
+// RichTextAttachment.tsx — renders one attachment block's body (spinner / error /
+// image preview / file chip). Pure presentational: the error Retry/Remove buttons
+// carry data-attachment-action + data-block-id hooks the editor delegates (so the
+// pure renderDoc stays callback-free). The read-only viewer renders the same markup
+// minus those buttons — it has no editor delegate, so they would do nothing.
+import { useId } from 'react';
+import { RotateCw, X } from 'lucide-react';
+import { Button } from '../Button';
+import { CircularProgress } from '../CircularProgress';
+import { Tooltip } from '../Tooltip';
+import { useTranslation } from '../../i18n';
+import type { Block } from './engine/model';
+import { safeHref } from './engine/safeHref';
+import { attachmentIsImage } from './engine/attachment';
+import { AttachFileIcon } from './attachmentIcon';
+import styles from './RichTextAttachment.module.scss';
+
+export function RichTextAttachment({ block, editable }: { block: Block; editable?: boolean }) {
+  const t = useTranslation();
+  const name = block.name ?? '';
+  const errorId = useId();
+
+  if (block.status === 'uploading') {
+    return (
+      <span className={styles.attachmentLoading}>
+        <CircularProgress size="sm" aria-label={t('richTextEditor.uploadingFile')} />
+        <span className={styles.attachmentName}>{name}</span>
+      </span>
+    );
+  }
+  if (block.status === 'error') {
+    const retry = t('richTextEditor.uploadRetry');
+    const remove = t('richTextEditor.uploadRemove');
+    // The failure (and its reason) is visible text, reachable in browse mode; the
+    // icon buttons also point aria-describedby at it so focusing Retry/Remove
+    // says WHY (a persistent state → property, per Hard rule 10).
+    return (
+      <span className={styles.attachmentError}>
+        <span className={styles.attachmentName}>{name}</span>
+        <span id={errorId}>
+          <span className={styles.attachmentLabel}>{t('richTextEditor.uploadFailed')}</span>
+          {block.uploadError && (
+            <>
+              {' '}
+              <span className={styles.attachmentReason}>{block.uploadError}</span>
+            </>
+          )}
+        </span>
+        {/* Actions only where the editor delegates them; read-only they'd be inert. */}
+        {editable && (
+          <>
+            <Tooltip content={retry}>
+              <Button
+                size="xs"
+                iconOnly
+                data-attachment-action="retry"
+                data-block-id={block.id}
+                aria-label={name ? `${retry} ${name}` : retry}
+                aria-describedby={errorId}
+              >
+                <RotateCw size={14} aria-hidden="true" />
+              </Button>
+            </Tooltip>
+            <Tooltip content={remove}>
+              <Button
+                size="xs"
+                iconOnly
+                variant="danger-outline"
+                data-attachment-action="remove"
+                data-block-id={block.id}
+                aria-label={name ? `${remove} ${name}` : remove}
+                aria-describedby={errorId}
+              >
+                <X size={14} aria-hidden="true" />
+              </Button>
+            </Tooltip>
+          </>
+        )}
+      </span>
+    );
+  }
+  // ready (or absent status on an imported doc)
+  const href = safeHref(block.src ?? '');
+  if (attachmentIsImage(block) && href) {
+    // A plain <img> (not the DS <Image>, whose wrapper hard-sets width/height:100%
+    // so the rendered size is decoupled from the width attr). Here the width attr +
+    // `height: auto` give the configured display size at natural aspect, and the
+    // `inline-block` lets the figure's `text-align` (data-align) position it.
+    return (
+      <img
+        className={styles.attachmentImg}
+        src={href}
+        // `??`, NOT `||`, and the one place in the library where that is right.
+        // `alt=""` is a real HTML value — "decorative, skip me" — so an empty
+        // `block.alt` is a choice to honour, not an unset to fall back from.
+        // Everywhere else in this library an empty label means unset; see
+        // AI-PRIMER.md, which names this as the exception.
+        alt={block.alt ?? name}
+        width={block.width}
+        height={block.height}
+        // Publish the natural aspect so the SCSS height cap (#644) can shrink the
+        // WIDTH instead of squashing the image. Read from the loaded image, not the
+        // block: a resize stores width only (height cleared). Set imperatively so
+        // React (which owns no `style` here) never re-renders it away.
+        onLoad={(e) => {
+          const img = e.currentTarget;
+          if (img.naturalWidth && img.naturalHeight)
+            img.style.setProperty(
+              '--rich-text-image-aspect',
+              String(img.naturalWidth / img.naturalHeight),
+            );
+        }}
+      />
+    );
+  }
+  return (
+    <a className={styles.attachmentChip} href={href} download rel="noopener noreferrer">
+      <AttachFileIcon />
+      <span className={styles.attachmentName}>{name}</span>
+    </a>
+  );
+}

package/src/components/RichText/_prose.scss

@@ -0,0 +1,79 @@
+// _prose.scss — shared rich-text prose styling. Applied via the `prose()` mixin
+// so <RichText> (read-only) and <RichTextEditor> render identically. Tokens only.
+@mixin prose {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+  color: var(--color-fg);
+  font-size: var(--font-size-md);
+  line-height: var(--line-height-normal);
+
+  :where(h1, h2, h3) {
+    font-weight: var(--font-weight-bold);
+    line-height: var(--line-height-tight);
+  }
+
+  :where(h1) {
+    font-size: var(--font-size-xl);
+  }
+
+  :where(h2) {
+    font-size: var(--font-size-lg);
+  }
+
+  :where(h3) {
+    font-size: var(--font-size-md);
+  }
+
+  :where(ul, ol) {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-1);
+    padding-inline-start: var(--space-5);
+  }
+
+  :where(blockquote) {
+    padding-inline-start: var(--space-3);
+    border-inline-start: var(--border-width-strong) solid var(--color-border);
+    color: var(--color-fg-muted);
+  }
+
+  :where(pre) {
+    padding: var(--space-3);
+    background: var(--color-bg-muted);
+    border-radius: var(--radius-md);
+    overflow-x: auto;
+    font-family: var(--font-family-mono);
+    font-size: var(--font-size-sm);
+  }
+
+  :where(code) {
+    font-family: var(--font-family-mono);
+    font-size: var(--font-size-code);
+  }
+
+  :where(:not(pre) > code) {
+    padding: 0 var(--space-1);
+    background: var(--color-bg-muted);
+    border-radius: var(--radius-sm);
+  }
+
+  // Bare anchors only. A styled link (a DS <Link> via renderLink, EntityChip,
+  // the attachment chip) carries a class and keeps its own decoration: this
+  // rule compiles to (0,1,0), the same as `.link`, so it used to win by
+  // source order and underline every <Link> at rest (#570). Not zero
+  // specificity — a consumer's global `a {}` reset must not strip prose links.
+  :where(a:not([class])) {
+    color: var(--color-accent);
+    text-decoration: underline;
+  }
+
+  :where([data-mention]) {
+    padding: 0 var(--space-1);
+    border-radius: var(--radius-sm);
+    background: var(--color-accent-bg-subtle);
+    color: var(--color-accent);
+    font-weight: var(--font-weight-medium);
+    white-space: nowrap;
+  }
+}

package/src/components/RichText/attachmentIcon.tsx

@@ -0,0 +1,24 @@
+// Split out of RichTextEditor/icons.tsx (#509). RichTextAttachment renders in
+// the read-only viewer as well as the editor, so the icon it needs cannot live
+// in the editor without RichText importing upward — which is the cycle this
+// change removes. RichTextEditor/icons.tsx re-exports it, so the toolbar is
+// unaffected.
+const base = {
+  width: 16,
+  height: 16,
+  viewBox: '0 0 24 24',
+  fill: 'none',
+  stroke: 'currentColor',
+  strokeWidth: 2,
+  strokeLinecap: 'round',
+  strokeLinejoin: 'round',
+  'aria-hidden': true,
+} as const;
+
+export function AttachFileIcon() {
+  return (
+    <svg {...base}>
+      <path d="M21.44 11.05l-9.19 9.19a5 5 0 0 1-7.07-7.07l9.19-9.19a3 3 0 0 1 4.24 4.24l-9.2 9.19a1 1 0 0 1-1.41-1.41l8.49-8.49" />
+    </svg>
+  );
+}

package/src/components/RichText/engine/attachment.ts

@@ -0,0 +1,154 @@
+// attachment.ts — attachment (void) block helpers + transforms. Pure + immutable.
+import type { RichDoc, Block, Point, Range } from './model';
+import { createBlock, nextId } from './model';
+import { findBlockIndex, blockLength, collapsedRange } from './position';
+import { sliceInlines, normalizeInlines } from './inlines';
+
+/**
+ * Fields for creating/patching an attachment block. All optional; only the
+ * provided keys are written (so a block stays canonical — no `undefined` keys).
+ * Mirrors the attachment fields on {@link Block}.
+ */
+export interface AttachmentAttrs {
+  /** Display name / chip label (usually the File's name). */
+  name?: string;
+  /** MIME type — `image/*` renders an inline preview, else a file chip. */
+  mime?: string;
+  /** The uploaded URL. Absent while `status: 'uploading'`. */
+  src?: string;
+  /** Natural image dimensions (layout hints). */
+  width?: number;
+  height?: number;
+  /**
+   * Image alt text. An EMPTY string is honoured, not treated as unset —
+   * `alt=""` is HTML's marker for a decorative image. This is the library's
+   * one exception to "an empty label means unset".
+   */
+  alt?: string;
+  /** Image alignment. */
+  align?: 'left' | 'center' | 'right';
+  /** Upload state. Defaults to `'ready'` when omitted. */
+  status?: 'uploading' | 'ready' | 'error';
+  /** Failure reason shown on an `error` block (from an `UploadError`). */
+  uploadError?: string;
+}
+
+/** True for void blocks (no editable text; caret sits adjacent, never inside). */
+export function isVoidBlock(block: Block): boolean {
+  return block.type === 'attachment';
+}
+
+/**
+ * Whether an attachment should render/serialize as an inline image (vs a file
+ * chip). Decided by `mime` (`image/*`), falling back to the URL extension. Shared
+ * by the renderer and the HTML/Markdown serializers so the rule never drifts.
+ */
+export function attachmentIsImage(block: Pick<Block, 'mime' | 'src'>): boolean {
+  if (block.mime) return block.mime.startsWith('image/');
+  return /\.(png|jpe?g|gif|webp|avif|svg)(\?|$)/i.test(block.src ?? '');
+}
+
+/**
+ * Whether an attachment is "settled" — its upload finished (`status: 'ready'`) OR
+ * it is a persisted/imported block whose transient `status` was dropped on
+ * serialization (`status` absent). Excludes in-flight (`uploading`) and failed
+ * (`error`) blocks. This is the SAME set the renderer treats as displayable, so
+ * the editor's resize-handle / Configure gates must use it (not a stricter
+ * `status === 'ready'`) or they silently disagree on persisted docs. See #263.
+ */
+export function isAttachmentSettled(block: Pick<Block, 'status'>): boolean {
+  return block.status === 'ready' || block.status == null;
+}
+
+function attachmentBlock(attrs: AttachmentAttrs): Block {
+  return {
+    id: nextId(),
+    type: 'attachment',
+    inlines: [],
+    status: attrs.status ?? 'ready',
+    ...(attrs.name !== undefined ? { name: attrs.name } : {}),
+    ...(attrs.mime !== undefined ? { mime: attrs.mime } : {}),
+    ...(attrs.src !== undefined ? { src: attrs.src } : {}),
+    ...(attrs.width !== undefined ? { width: attrs.width } : {}),
+    ...(attrs.height !== undefined ? { height: attrs.height } : {}),
+    ...(attrs.alt !== undefined ? { alt: attrs.alt } : {}),
+    ...(attrs.align !== undefined ? { align: attrs.align } : {}),
+  };
+}
+
+/**
+ * Split the block at `point` and insert an attachment block between the halves.
+ * Always leaves an editable paragraph AFTER the attachment (the caret's home);
+ * the caret lands at offset 0 of that trailing block. If `point` is inside a void
+ * block, inserts after it instead of splitting. Returns the new block's
+ * `attachmentId` so callers needn't re-derive it from array position (`null` on
+ * the no-op path when `point.blockId` isn't found).
+ */
+export function insertAttachmentBlock(
+  doc: RichDoc,
+  point: Point,
+  attrs: AttachmentAttrs,
+): { doc: RichDoc; selection: Range; attachmentId: string | null } {
+  const idx = findBlockIndex(doc, point.blockId);
+  if (idx === -1) {
+    return { doc, selection: collapsedRange(point.blockId, point.offset), attachmentId: null };
+  }
+  const block = doc.blocks[idx];
+  const att = attachmentBlock(attrs);
+
+  if (isVoidBlock(block)) {
+    const after = createBlock('paragraph');
+    const blocks = [...doc.blocks.slice(0, idx + 1), att, after, ...doc.blocks.slice(idx + 1)];
+    return { doc: { blocks }, selection: collapsedRange(after.id), attachmentId: att.id };
+  }
+
+  const left: Block = {
+    ...block,
+    inlines: normalizeInlines(sliceInlines(block.inlines, 0, point.offset)),
+  };
+  const rightInlines = normalizeInlines(
+    sliceInlines(block.inlines, point.offset, blockLength(block)),
+  );
+  const right: Block = {
+    ...createBlock(block.type, '', { level: block.level, depth: block.depth }),
+    inlines: rightInlines,
+  };
+  const blocks = [...doc.blocks.slice(0, idx), left, att, right, ...doc.blocks.slice(idx + 1)];
+  return { doc: { blocks }, selection: collapsedRange(right.id), attachmentId: att.id };
+}
+
+/** Patch an attachment block's fields by id. Same-ref no-op if absent/not attachment. */
+export function updateAttachmentBlock(doc: RichDoc, id: string, patch: AttachmentAttrs): RichDoc {
+  const idx = findBlockIndex(doc, id);
+  if (idx === -1 || doc.blocks[idx].type !== 'attachment') return doc;
+  // Only write keys that were actually provided, so the block stays canonical
+  // (no `key: undefined` entries) — mirrors how attachmentBlock() builds one.
+  const clean: AttachmentAttrs = {};
+  for (const [k, v] of Object.entries(patch)) {
+    if (v !== undefined) (clean as Record<string, unknown>)[k] = v;
+  }
+  const blocks = doc.blocks.slice();
+  blocks[idx] = { ...blocks[idx], ...clean };
+  return { blocks };
+}
+
+/**
+ * Remove the given keys from an attachment block (canonical "unset" — e.g.
+ * resetting width/height to natural size). Same-ref no-op if the id is absent,
+ * not an attachment, or none of the keys are present.
+ */
+export function clearAttachmentFields(
+  doc: RichDoc,
+  id: string,
+  keys: ('width' | 'height' | 'align' | 'alt' | 'uploadError')[],
+): RichDoc {
+  const idx = findBlockIndex(doc, id);
+  if (idx === -1 || doc.blocks[idx].type !== 'attachment') return doc;
+  const block = doc.blocks[idx];
+  if (!keys.some((k) => k in block)) return doc;
+  const next = { ...block };
+  for (const k of keys) delete next[k as keyof typeof next];
+  const blocks = doc.blocks.slice();
+  blocks[idx] = next;
+  return { blocks };
+}

package/src/components/RichText/engine/autolink.ts

@@ -0,0 +1,64 @@
+// autolink.ts — pure URL detection for the editor's autolink (type + paste) and
+// the RichText importer. No DOM. hrefs pass through safeHref so only safe schemes
+// become links.
+import type { Inline } from './model';
+import { safeHref } from './safeHref';
+
+// http(s)://… or a bare www.… host. Kept deliberately conservative.
+const URL_RE = /\b(?:https?:\/\/|www\.)[^\s<>()[\]]+/gi;
+// Strip trailing sentence punctuation that is unlikely to be part of the URL.
+const TRAILING = /[.,;:!?'"]+$/;
+
+function normalize(raw: string): { url: string; href: string } | null {
+  let url = raw.replace(TRAILING, '');
+  // Drop an unmatched closing bracket/paren (e.g. "(https://a.com)").
+  if (/[)\]]$/.test(url) && !/[([]/.test(url)) url = url.slice(0, -1);
+  if (url === '') return null;
+  const candidate = url.startsWith('www.') ? `https://${url}` : url;
+  const safe = safeHref(candidate);
+  if (!safe || !/^https?:/i.test(safe)) return null;
+  return { url, href: safe };
+}
+
+/** The URL that ends exactly at the end of `text`, or null. (For the type rule:
+ *  the caller passes the text up to the caret.) */
+export function findUrl(text: string): { start: number; end: number; href: string } | null {
+  let m: RegExpExecArray | null;
+  URL_RE.lastIndex = 0;
+  let last: { start: number; end: number; href: string; rawEnd: number } | null = null;
+  while ((m = URL_RE.exec(text)) !== null) {
+    const norm = normalize(m[0]);
+    if (!norm) continue;
+    const start = m.index;
+    const end = start + norm.url.length;
+    // `rawEnd` is where the raw match ended (incl. stripped trailing punctuation /
+    // brackets), so a URL at the caret followed only by punctuation still counts.
+    const rawEnd = start + m[0].length;
+    last = { start, end, href: norm.href, rawEnd };
+  }
+  // Only return when the matched URL reaches the end of `text` — allowing for
+  // trailing punctuation/brackets that `normalize` stripped from `end` and for a
+  // closing bracket/paren the regex itself excluded (e.g. `(https://a.com)`).
+  if (!last) return null;
+  const tail = text.slice(last.rawEnd);
+  if (!/^[.,;:!?'")\]]*$/.test(tail)) return null;
+  return { start: last.start, end: last.end, href: last.href };
+}
+
+/** Split `text` into plain + link runs (for paste / import). */
+export function linkifyRuns(text: string): Inline[] {
+  const runs: Inline[] = [];
+  let i = 0;
+  let m: RegExpExecArray | null;
+  URL_RE.lastIndex = 0;
+  while ((m = URL_RE.exec(text)) !== null) {
+    const norm = normalize(m[0]);
+    if (!norm) continue;
+    const start = m.index;
+    if (start > i) runs.push({ text: text.slice(i, start), marks: [] });
+    runs.push({ text: norm.url, marks: [{ type: 'link', href: norm.href }] });
+    i = start + norm.url.length;
+  }
+  if (i < text.length) runs.push({ text: text.slice(i), marks: [] });
+  return runs.length ? runs : [{ text, marks: [] }];
+}