Open-Source-Legal
diff --git a/‎CHANGELOG.md‎
Lines changed: 68 additions & 3 deletions b/‎CHANGELOG.md‎
Lines changed: 68 additions & 3 deletions
diff --git a/‎docs/assets/images/screenshots/auto/caml--editor--full-template.png‎
-227 Bytes b/‎docs/assets/images/screenshots/auto/caml--editor--full-template.png‎
-227 Bytes
diff --git a/‎docs/assets/images/screenshots/auto/caml--editor--new-article.png‎
-34.4 KB b/‎docs/assets/images/screenshots/auto/caml--editor--new-article.png‎
-34.4 KB
diff --git a/‎docs/assets/images/screenshots/auto/caml--embed-error-fallback--default.png‎
7.66 KB b/‎docs/assets/images/screenshots/auto/caml--embed-error-fallback--default.png‎
7.66 KB
diff --git a/‎frontend/src/assets/configurations/constants.ts‎
Lines changed: 0 additions & 1 deletion b/‎frontend/src/assets/configurations/constants.ts‎
Lines changed: 0 additions & 1 deletion
diff --git a/‎frontend/src/components/corpuses/CamlArticleEditor.tsx‎
Lines changed: 124 additions & 4 deletions b/‎frontend/src/components/corpuses/CamlArticleEditor.tsx‎
Lines changed: 124 additions & 4 deletions
diff --git a/‎frontend/src/components/corpuses/caml/CamlDirectiveRenderer.tsx‎
Lines changed: 3 additions & 1 deletion b/‎frontend/src/components/corpuses/caml/CamlDirectiveRenderer.tsx‎
Lines changed: 3 additions & 1 deletion
diff --git a/‎frontend/src/components/extracts/ExtractGridEmbed.tsx‎
Lines changed: 3 additions & 0 deletions b/‎frontend/src/components/extracts/ExtractGridEmbed.tsx‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎frontend/src/components/extracts/__tests__/formatCellValue.test.ts‎
Lines changed: 91 additions & 19 deletions b/‎frontend/src/components/extracts/__tests__/formatCellValue.test.ts‎
Lines changed: 91 additions & 19 deletions
diff --git a/‎frontend/src/hooks/useCamlComponentRenderer.tsx‎
Lines changed: 6 additions & 1 deletion b/‎frontend/src/hooks/useCamlComponentRenderer.tsx‎
Lines changed: 6 additions & 1 deletion
@@ -372,7 +372,6 @@ export const EXTRACT_GRID_EMBED_CELL_LIMIT = 500;
  * `EXTRACT_GRID_EMBED_CELL_LIMIT` on the server side.
  */
 export const EXTRACT_GRID_EMBED_MAX_ROWS = 200;
-
 // Datacell status indicator colors (used in ExtractGridEmbed status dots).
 // Values reference OS_LEGAL_COLORS design tokens for consistency.
 export const DATACELL_STATUS_COLORS = {
 
@@ -240,19 +240,25 @@ const ExtractPickerDropdown = styled.div`
   box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
 `;
 
-const ExtractPickerItem = styled.button`
+const ExtractPickerItem = styled.button<{ $active?: boolean }>`
   display: block;
   width: 100%;
   padding: 0.5rem 0.75rem;
   border: none;
-  background: transparent;
+  /* Keyboard-active ($active) and mouse-hover share the same visual highlight. */
+  background: ${(p) =>
+    p.$active ? OS_LEGAL_COLORS.surfaceLight : "transparent"};
   text-align: left;
   font-size: 0.8125rem;
   color: ${OS_LEGAL_COLORS.textPrimary};
   cursor: pointer;
   &:hover {
     background: ${OS_LEGAL_COLORS.surfaceLight};
   }
+  &:focus-visible {
+    outline: 2px solid ${OS_LEGAL_COLORS.accent};
+    outline-offset: -2px;
+  }
 `;
 
 const ExtractPickerEmpty = styled.div`
@@ -364,8 +370,12 @@ export const CamlArticleEditor: React.FC<CamlArticleEditorProps> = ({
   const [isNew, setIsNew] = useState(false);
   const [showCloseConfirm, setShowCloseConfirm] = useState(false);
   const [showExtractPicker, setShowExtractPicker] = useState(false);
+  // Index of the keyboard-focused option within the extract picker dropdown.
+  // `-1` means no option is focused (initial state when the dropdown opens).
+  const [activeExtractIndex, setActiveExtractIndex] = useState<number>(-1);
   const textareaRef = useRef<HTMLTextAreaElement>(null);
   const extractPickerRef = useRef<HTMLDivElement>(null);
+  const extractPickerTriggerRef = useRef<HTMLButtonElement>(null);
 
   // Query for existing Readme.CAML
   const articleVars = useMemo<GetCorpusArticleInput>(
@@ -534,6 +544,14 @@ export const CamlArticleEditor: React.FC<CamlArticleEditorProps> = ({
     return () => document.removeEventListener("mousedown", handleClickOutside);
   }, [showExtractPicker]);
 
+  // Reset the keyboard-focused option whenever the picker closes so the next
+  // open starts in a clean state.
+  useEffect(() => {
+    if (!showExtractPicker) {
+      setActiveExtractIndex(-1);
+    }
+  }, [showExtractPicker]);
+
   /** Insert a component marker as a prose block at the cursor. */
   const handleInsertComponent = useCallback(
     (type: string, props: Record<string, string>) => {
@@ -565,6 +583,80 @@ export const CamlArticleEditor: React.FC<CamlArticleEditorProps> = ({
     []
   );
 
+  /**
+   * Keyboard handler for the extract picker (listbox pattern).
+   *
+   * - ArrowDown / ArrowUp move the focused option (wrapping at the ends).
+   * - Home / End jump to first / last option.
+   * - Enter selects the focused option (inserts the extract grid marker).
+   * - Escape closes the dropdown and returns focus to the trigger button.
+   *
+   * Attached to the trigger button (role="combobox") so
+   * `aria-activedescendant` and the keyboard handler share the same DOM
+   * focus context — required by WAI-ARIA for virtual-focus patterns.
+   */
+  const handleExtractPickerKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLButtonElement>) => {
+      if (!showExtractPicker) return;
+      const count = corpusExtracts.length;
+
+      switch (event.key) {
+        case "Escape":
+          event.preventDefault();
+          setShowExtractPicker(false);
+          extractPickerTriggerRef.current?.focus();
+          break;
+        case "ArrowDown":
+          if (count === 0) return;
+          event.preventDefault();
+          setActiveExtractIndex((prev) => (prev + 1 >= count ? 0 : prev + 1));
+          break;
+        case "ArrowUp":
+          if (count === 0) return;
+          event.preventDefault();
+          // `prev <= 0` covers both `0` (first item → wrap to last) and `-1`
+          // (no item focused → jump to last). This is intentional per WAI-ARIA
+          // Authoring Practices for listbox keyboard interaction.
+          setActiveExtractIndex((prev) => (prev <= 0 ? count - 1 : prev - 1));
+          break;
+        case "Home":
+          if (count === 0) return;
+          event.preventDefault();
+          setActiveExtractIndex(0);
+          break;
+        case "End":
+          if (count === 0) return;
+          event.preventDefault();
+          setActiveExtractIndex(count - 1);
+          break;
+        case "Enter": {
+          if (count === 0) return;
+          // Only act when a menu option is focused — otherwise let the
+          // default button behaviour on the trigger toggle the picker.
+          if (activeExtractIndex < 0 || activeExtractIndex >= count) return;
+          event.preventDefault();
+          event.stopPropagation();
+          const selected = corpusExtracts[activeExtractIndex];
+          if (selected) {
+            // handleInsertComponent already calls setShowExtractPicker(false)
+            // internally, so the picker is closed as part of the insertion.
+            handleInsertComponent("extract-grid", { extractId: selected.id });
+            extractPickerTriggerRef.current?.focus();
+          }
+          break;
+        }
+        default:
+          break;
+      }
+    },
+    [
+      showExtractPicker,
+      corpusExtracts,
+      activeExtractIndex,
+      handleInsertComponent,
+    ]
+  );
+
   // Markdown renderer with generic component marker interception
   const renderMarkdownPreview = useCamlComponentRenderer(CAML_COMPONENTS);
 
@@ -596,9 +688,28 @@ export const CamlArticleEditor: React.FC<CamlArticleEditorProps> = ({
             <EditorToolbar>
               <div ref={extractPickerRef} style={{ position: "relative" }}>
                 <ToolbarBtn
+                  ref={extractPickerTriggerRef}
                   type="button"
+                  // WAI-ARIA combobox pattern: role="combobox" is required for
+                  // aria-activedescendant to be valid.  A plain role="button"
+                  // is NOT in the spec's allowed list, causing screen readers
+                  // to silently ignore the active descendant announcement.
+                  role="combobox"
                   aria-haspopup="listbox"
                   aria-expanded={showExtractPicker}
+                  aria-controls={
+                    showExtractPicker
+                      ? "caml-extract-picker-listbox"
+                      : undefined
+                  }
+                  aria-activedescendant={
+                    showExtractPicker &&
+                    activeExtractIndex >= 0 &&
+                    activeExtractIndex < corpusExtracts.length
+                      ? `caml-extract-picker-option-${corpusExtracts[activeExtractIndex].id}`
+                      : undefined
+                  }
+                  onKeyDown={handleExtractPickerKeyDown}
                   onClick={(e) => {
                     e.stopPropagation();
                     setShowExtractPicker((v) => !v);
@@ -610,7 +721,11 @@ export const CamlArticleEditor: React.FC<CamlArticleEditorProps> = ({
                   Insert Extract Grid
                 </ToolbarBtn>
                 {showExtractPicker && (
-                  <ExtractPickerDropdown role="listbox">
+                  <ExtractPickerDropdown
+                    id="caml-extract-picker-listbox"
+                    role="listbox"
+                    aria-label="Corpus extracts"
+                  >
                     {extractsLoading ? (
                       <ExtractPickerEmpty>
                         Loading extracts...
@@ -620,11 +735,16 @@ export const CamlArticleEditor: React.FC<CamlArticleEditorProps> = ({
                         No extracts found for this corpus.
                       </ExtractPickerEmpty>
                     ) : (
-                      corpusExtracts.map((ext) => (
+                      corpusExtracts.map((ext, index) => (
                         <ExtractPickerItem
+                          tabIndex={-1}
                           type="button"
                           role="option"
+                          id={`caml-extract-picker-option-${ext.id}`}
                           key={ext.id}
+                          $active={index === activeExtractIndex}
+                          aria-selected={false}
+                          onMouseEnter={() => setActiveExtractIndex(index)}
                           onClick={() =>
                             handleInsertComponent("extract-grid", {
                               extractId: ext.id,
 
@@ -148,8 +148,10 @@ export const CamlDirectiveRenderer: React.FC<CamlDirectiveRendererProps> = ({
 
       // Check for embedded component markers (e.g. [component:extract-grid ...])
       // Component-marker blocks are assumed to contain no inline directives.
+      // Pass `md` as the React key so multiple markers in the same article
+      // reconcile stably (otherwise React warns about missing `key` props).
       if (componentRegistry) {
-        const resolved = resolveComponentMarker(md, componentRegistry);
+        const resolved = resolveComponentMarker(md, componentRegistry, md);
         if (resolved) {
           return (
             <ErrorBoundary
 
@@ -256,6 +256,9 @@ export const ExtractGridEmbed: React.FC<ExtractGridEmbedProps> = ({
       limit: EXTRACT_GRID_EMBED_CELL_LIMIT,
     },
     skip: !extractId,
+    // NOTE: If another caller queries the same extract with a different `first`
+    // value (e.g. undefined), Apollo will serve this capped result from cache.
+    // Acceptable while there is a single call site; revisit with #1204 cleanup.
     fetchPolicy: "cache-first",
   });
 
 
@@ -1,9 +1,38 @@
-import { describe, expect, it } from "vitest";
+import { describe, it, expect } from "vitest";
+import {
+  formatCellValue,
+  truncateAtCodePoint,
+} from "../../../utils/formatters";
 
-import { EXTRACT_GRID_CELL_TRUNCATE_LENGTH } from "../../../assets/configurations/constants";
-import { formatCellValue } from "../../../utils/formatters";
+describe("truncateAtCodePoint()", () => {
+  it("returns the string unchanged when within limit", () => {
+    expect(truncateAtCodePoint("hello", 10)).toBe("hello");
+  });
+
+  it("truncates at code-point boundary with ellipsis", () => {
+    const result = truncateAtCodePoint("a".repeat(150), 100);
+    expect(result.endsWith("\u2026")).toBe(true);
+    expect(Array.from(result).length).toBe(101);
+  });
+
+  it("handles emoji without splitting surrogate pairs", () => {
+    const emojis = "\u{1F600}".repeat(105);
+    const result = truncateAtCodePoint(emojis, 100);
+    expect(result).not.toContain("\uFFFD");
+    expect(result.endsWith("\u2026")).toBe(true);
+    expect(Array.from(result).length).toBe(101);
+  });
+
+  it("returns unchanged when UTF-16 length exceeds limit but code-point count does not", () => {
+    // 50 emoji = 50 code points but 100 UTF-16 code units
+    const emojis = "\u{1F600}".repeat(50);
+    expect(emojis.length).toBeGreaterThan(50);
+    expect(Array.from(emojis).length).toBe(50);
+    expect(truncateAtCodePoint(emojis, 50)).toBe(emojis);
+  });
+});
 
-describe("formatCellValue", () => {
+describe("formatCellValue()", () => {
   it("returns em-dash for null", () => {
     expect(formatCellValue(null)).toBe("\u2014");
   });
@@ -20,31 +49,74 @@ describe("formatCellValue", () => {
     expect(formatCellValue(false)).toBe("No");
   });
 
-  it("returns stringified number", () => {
+  it("converts number to string", () => {
     expect(formatCellValue(42)).toBe("42");
     expect(formatCellValue(0)).toBe("0");
   });
 
-  it("returns plain string as-is", () => {
+  it("passes through short strings", () => {
     expect(formatCellValue("hello")).toBe("hello");
   });
 
-  it("returns JSON for short objects", () => {
-    const obj = { key: "val" };
-    expect(formatCellValue(obj)).toBe(JSON.stringify(obj));
+  it("returns JSON for short objects (fast path)", () => {
+    const obj = { key: "value" };
+    expect(formatCellValue(obj)).toBe('{"key":"value"}');
   });
 
-  it("truncates JSON for objects exceeding the truncation length", () => {
-    const longObj: Record<string, string> = {};
-    for (let i = 0; i < 50; i++) {
-      longObj[`key${i}`] = `value-${i}-padding`;
-    }
-    const json = JSON.stringify(longObj);
-    // Precondition: the generated JSON is indeed longer than the limit.
-    expect(json.length).toBeGreaterThan(EXTRACT_GRID_CELL_TRUNCATE_LENGTH);
+  it("truncates long JSON at code-point boundary with ellipsis", () => {
+    // Build an object whose JSON representation exceeds 100 chars
+    const longValue = "x".repeat(120);
+    const obj = { data: longValue };
+    const result = formatCellValue(obj);
+    // Should end with ellipsis and be at most 101 chars (100 code points + ellipsis)
+    expect(result.endsWith("\u2026")).toBe(true);
+    const codePoints = Array.from(result);
+    // 100 code points from the slice + 1 ellipsis = 101
+    expect(codePoints.length).toBe(101);
+  });
+
+  it("handles emoji in long objects without splitting surrogate pairs", () => {
+    // Each emoji is 1 code point but 2 UTF-16 code units (surrogate pair).
+    // JSON wrapper `{"e":"..."}` adds 8 code points, so 95 emoji = 103 code points > 100.
+    const emojis = "\u{1F600}".repeat(95);
+    const obj = { e: emojis };
+    const result = formatCellValue(obj);
+    // Should truncate cleanly without U+FFFD replacement characters
+    expect(result).not.toContain("\uFFFD");
+    expect(result.endsWith("\u2026")).toBe(true);
+    const codePoints = Array.from(result);
+    expect(codePoints.length).toBe(101);
+  });
 
-    const result = formatCellValue(longObj);
-    expect(result.length).toBe(EXTRACT_GRID_CELL_TRUNCATE_LENGTH + 1); // +1 for ellipsis char
+  it("truncates long raw strings at code-point boundary with ellipsis", () => {
+    const longString = "a".repeat(150);
+    const result = formatCellValue(longString);
     expect(result.endsWith("\u2026")).toBe(true);
+    const codePoints = Array.from(result);
+    expect(codePoints.length).toBe(101);
+  });
+
+  it("handles emoji in long raw strings without splitting surrogate pairs", () => {
+    const emojis = "\u{1F600}".repeat(105);
+    const result = formatCellValue(emojis);
+    expect(result).not.toContain("\uFFFD");
+    expect(result.endsWith("\u2026")).toBe(true);
+    const codePoints = Array.from(result);
+    expect(codePoints.length).toBe(101);
+  });
+
+  it("does not truncate object whose JSON has >100 UTF-16 units but <=100 code points", () => {
+    // Build a string of 48 emoji: JSON = {"e":"<48 emoji>"} = 7 wrapper chars + 48 code points = 55 code points
+    // But 7 + 48*2 = 103 UTF-16 units (exceeds 100 in .length but not in code points)
+    const emojis = "\u{1F600}".repeat(48);
+    const obj = { e: emojis };
+    const json = JSON.stringify(obj);
+    // Verify our premise: UTF-16 length > 100 but code point count <= 100
+    expect(json.length).toBeGreaterThan(100);
+    expect(Array.from(json).length).toBeLessThanOrEqual(100);
+    const result = formatCellValue(obj);
+    // Should return the full JSON without truncation
+    expect(result).toBe(json);
+    expect(result.endsWith("\u2026")).toBe(false);
   });
 });
@@ -29,7 +29,12 @@ export function useCamlComponentRenderer(
 ): (md: string) => React.ReactNode {
   return useCallback(
     (md: string) => {
-      const resolved = resolveComponentMarker(md, registry);
+      // Use the marker string as the React key so that multiple
+      // `[component:...]` blocks in a single article each get a stable,
+      // unique identity for reconciliation. Without a key, React warns
+      // "Each child in a list should have a unique 'key' prop" and falls
+      // back to positional reconciliation.
+      const resolved = resolveComponentMarker(md, registry, md);
       if (resolved) {
         return (
           <ErrorBoundary