@startsimpli/ui 0.4.55 → 0.4.57

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.55",
+  "version": "0.4.57",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -41,8 +41,8 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@startsimpli/auth": "0.4.29",
-    "@startsimpli/api": "0.5.44"
+    "@startsimpli/api": "0.5.44",
+    "@startsimpli/auth": "0.4.30"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {

package/src/components/kanban/BoardCard.tsx

@@ -0,0 +1,156 @@
+'use client'
+
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+
+const ENTITIES: Record<string, string> = {
+  '&amp;': '&',
+  '&lt;': '<',
+  '&gt;': '>',
+  '&quot;': '"',
+  '&#39;': "'",
+  '&nbsp;': ' ',
+}
+
+/**
+ * Flatten markdown / HTML / whitespace-noisy text into a single-line preview,
+ * clamped to `maxChars` on a word boundary. Board cards get a readable content
+ * snippet without pulling in a full markdown renderer (startsim-768w.17.3): the
+ * pipeline writes long article bodies to `data.content`, and a raw slice of that
+ * shows heading hashes, link syntax and code fences.
+ */
+export function toPlainSnippet(
+  input: string | null | undefined,
+  maxChars = 240,
+): string {
+  if (!input) return ''
+  let s = String(input)
+  s = s.replace(/```[\s\S]*?```/g, ' ') // fenced code blocks
+  s = s.replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1') // images -> alt text
+  s = s.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') // links -> link text
+  s = s.replace(/<[^>]+>/g, ' ') // html tags
+  s = s.replace(/^[ \t]*[#>\-*+]+[ \t]+/gm, ' ') // heading / list / quote markers
+  s = s.replace(/[*_`~]+/g, '') // inline emphasis / code marks
+  s = s.replace(/&[a-z#0-9]+;/gi, (m) => ENTITIES[m.toLowerCase()] ?? ' ')
+  s = s.replace(/\s+/g, ' ').trim()
+  if (s.length <= maxChars) return s
+  const cut = s.slice(0, maxChars)
+  const lastSpace = cut.lastIndexOf(' ')
+  // cut back to the last whole word when that boundary is in the back half,
+  // otherwise hard-cut (e.g. a single very long token has no usable boundary)
+  const body = lastSpace > maxChars * 0.5 ? cut.slice(0, lastSpace) : cut
+  return body.trimEnd() + '…'
+}
+
+const LINE_CLAMP: Record<number, string> = {
+  2: 'line-clamp-2',
+  3: 'line-clamp-3',
+  4: 'line-clamp-4',
+  5: 'line-clamp-5',
+  6: 'line-clamp-6',
+}
+
+export interface BoardCardMeta {
+  label: string
+  value: React.ReactNode
+}
+
+export interface BoardCardProps {
+  /** Card heading (record name / title). */
+  title: React.ReactNode
+  /** Raw content (markdown / HTML / plain); shown as a clamped plain-text preview. */
+  snippet?: string | null
+  /** Max plain-text characters for the snippet (default 240). */
+  snippetMaxChars?: number
+  /** Tailwind line-clamp count for the snippet (default 3). */
+  snippetLines?: 2 | 3 | 4 | 5 | 6
+  /** Source / host label or link, shown under the snippet. */
+  source?: React.ReactNode
+  /** Compact key/value chips for short declared attributes. */
+  meta?: BoardCardMeta[]
+  /** Opens the record detail; wraps the title as a button when provided. */
+  onOpen?: () => void
+  /**
+   * Footer slot — e.g. a status `<Select>`. Pointer/click events inside are
+   * stopped so interacting with a control never starts a drag on the card.
+   */
+  footer?: React.ReactNode
+  className?: string
+}
+
+/**
+ * A content-aware board card: title + readable content snippet + source + a few
+ * meta chips + a footer slot. Presentation-only and drag-agnostic — the
+ * KanbanBoard wraps it in a Draggable; this just renders the content the epic's
+ * News Item board was missing (title-only cards). Reusable for any entity board.
+ */
+export function BoardCard({
+  title,
+  snippet,
+  snippetMaxChars = 240,
+  snippetLines = 3,
+  source,
+  meta,
+  onOpen,
+  footer,
+  className,
+}: BoardCardProps) {
+  const preview = toPlainSnippet(snippet, snippetMaxChars)
+  const hasSource = source != null && source !== ''
+  return (
+    <div
+      className={cn(
+        'm-2 rounded-md border bg-white p-3 shadow-sm dark:bg-neutral-900',
+        className,
+      )}
+    >
+      {onOpen ? (
+        <button
+          type="button"
+          onClick={onOpen}
+          className="block w-full text-left text-sm font-medium leading-snug hover:underline"
+        >
+          {title}
+        </button>
+      ) : (
+        <div className="text-sm font-medium leading-snug">{title}</div>
+      )}
+
+      {preview && (
+        <p
+          className={cn(
+            'mt-1 text-xs leading-snug text-neutral-600 dark:text-neutral-300',
+            LINE_CLAMP[snippetLines],
+          )}
+        >
+          {preview}
+        </p>
+      )}
+
+      {hasSource && (
+        <div className="mt-1.5 truncate text-xs text-neutral-400">{source}</div>
+      )}
+
+      {meta && meta.length > 0 && (
+        <dl className="mt-1 space-y-0.5">
+          {meta.map((m, i) => (
+            <div key={i} className="flex gap-1 text-xs text-neutral-600 dark:text-neutral-300">
+              <dt className="capitalize text-neutral-400">{m.label}:</dt>
+              <dd className="truncate">{m.value}</dd>
+            </div>
+          ))}
+        </dl>
+      )}
+
+      {footer != null && (
+        <div
+          className="mt-2"
+          onClick={(e) => e.stopPropagation()}
+          onPointerDown={(e) => e.stopPropagation()}
+        >
+          {footer}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/kanban/__tests__/board-card.test.tsx

@@ -0,0 +1,77 @@
+import { render, screen, fireEvent } from '@testing-library/react'
+import { BoardCard, toPlainSnippet } from '../BoardCard'
+
+describe('toPlainSnippet', () => {
+  it('returns empty string for nullish/empty input', () => {
+    expect(toPlainSnippet(null)).toBe('')
+    expect(toPlainSnippet(undefined)).toBe('')
+    expect(toPlainSnippet('')).toBe('')
+  })
+
+  it('strips markdown headings, emphasis, links and code fences', () => {
+    const md = '# Title\n\nSome **bold** and _italic_ with a [link](https://x.io).\n\n```js\ncode()\n```'
+    const out = toPlainSnippet(md)
+    expect(out).toBe('Title Some bold and italic with a link.')
+    expect(out).not.toMatch(/[#*_`]|\]\(|```/)
+  })
+
+  it('strips html tags and decodes common entities', () => {
+    expect(toPlainSnippet('<p>Gold &amp; silver &lt;up&gt;</p>')).toBe('Gold & silver <up>')
+  })
+
+  it('collapses whitespace to single spaces', () => {
+    expect(toPlainSnippet('a\n\n  b\t c')).toBe('a b c')
+  })
+
+  it('truncates on a word boundary with an ellipsis when over the limit', () => {
+    // cut(12) = "one two thre"; last boundary at 7 -> back to the whole word
+    expect(toPlainSnippet('one two three four five six', 12)).toBe('one two…')
+  })
+
+  it('hard-cuts a single long token with no usable word boundary', () => {
+    expect(toPlainSnippet('supercalifragilisticexpialidocious', 10)).toBe('supercalif…')
+  })
+
+  it('does not truncate when within the limit', () => {
+    expect(toPlainSnippet('short', 240)).toBe('short')
+  })
+})
+
+describe('BoardCard', () => {
+  it('renders the title and a plain-text content snippet (markdown stripped)', () => {
+    render(<BoardCard title="Gold hits record" snippet={'## Lead\n\nPrices **surged** today.'} />)
+    expect(screen.getByText('Gold hits record')).toBeInTheDocument()
+    expect(screen.getByText('Lead Prices surged today.')).toBeInTheDocument()
+  })
+
+  it('renders source and meta chips', () => {
+    render(
+      <BoardCard
+        title="T"
+        source="reuters.com"
+        meta={[{ label: 'market', value: 'UAE' }]}
+      />,
+    )
+    expect(screen.getByText('reuters.com')).toBeInTheDocument()
+    expect(screen.getByText('market:')).toBeInTheDocument()
+    expect(screen.getByText('UAE')).toBeInTheDocument()
+  })
+
+  it('calls onOpen when the title is clicked', () => {
+    const onOpen = jest.fn()
+    render(<BoardCard title="Open me" onOpen={onOpen} />)
+    fireEvent.click(screen.getByRole('button', { name: 'Open me' }))
+    expect(onOpen).toHaveBeenCalledTimes(1)
+  })
+
+  it('stops footer clicks from bubbling (so a control never starts a card drag)', () => {
+    const outer = jest.fn()
+    render(
+      <div onClick={outer}>
+        <BoardCard title="T" footer={<button type="button">status</button>} />
+      </div>,
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'status' }))
+    expect(outer).not.toHaveBeenCalled()
+  })
+})

package/src/components/kanban/index.ts

@@ -1,2 +1,4 @@
 export { KanbanBoard, resolveKanbanMove } from './KanbanBoard'
 export type { KanbanBoardProps, KanbanColumnConfig, KanbanMove } from './KanbanBoard'
+export { BoardCard, toPlainSnippet } from './BoardCard'
+export type { BoardCardProps, BoardCardMeta } from './BoardCard'

package/src/components/validation/__tests__/checks.test.ts

@@ -189,3 +189,98 @@ describe('overallStatus', () => {
     expect(overallStatus(checks)).toBe('fail');
   });
 });
+
+describe('runContentChecks — locations (768w.16.15.3 jump-to-issue)', () => {
+  it('omits locations on a passing check — there is nothing to jump to', () => {
+    const checks = runContentChecks({ blog: words(450) });
+    expect(find(checks, 'blog-words')!.status).toBe('pass');
+    expect(find(checks, 'blog-words')!.locations).toBeUndefined();
+    expect(find(checks, 'no-hype')!.status).toBe('pass');
+    expect(find(checks, 'no-hype')!.locations).toBeUndefined();
+  });
+
+  it('points a failing band check at its field with no span to highlight', () => {
+    const checks = runContentChecks({ blog: words(10) });
+    const c = find(checks, 'blog-words')!;
+    expect(c.status).toBe('warn');
+    expect(c.locations).toEqual([{ field: 'blog' }]);
+    // a word count is not a substring — nothing to highlight inside the field
+    expect(c.locations![0].matches).toBeUndefined();
+  });
+
+  it('maps each band check to its own field', () => {
+    const checks = runContentChecks({
+      headline: words(1),
+      linkedin: words(2),
+      tags: 'a',
+      metaDescription: 'short',
+    });
+    expect(find(checks, 'headline-words')!.locations).toEqual([{ field: 'headline' }]);
+    expect(find(checks, 'linkedin-words')!.locations).toEqual([{ field: 'linkedin' }]);
+    expect(find(checks, 'tags-count')!.locations).toEqual([{ field: 'tags' }]);
+    expect(find(checks, 'meta-length')!.locations).toEqual([{ field: 'metaDescription' }]);
+  });
+
+  it('locates a missing [link] placeholder at the linkedin field', () => {
+    const checks = runContentChecks({ linkedin: words(200) });
+    const c = find(checks, 'link-placeholder')!;
+    expect(c.status).toBe('warn');
+    expect(c.locations).toEqual([{ field: 'linkedin' }]);
+  });
+
+  it('locates hype words in the SPECIFIC field they appear in, not the joined haystack', () => {
+    const checks = runContentChecks({
+      headline: 'a calm headline',
+      blog: 'this is revolutionary work',
+      linkedin: 'nothing to see [link]',
+    });
+    const c = find(checks, 'no-hype')!;
+    expect(c.status).toBe('fail');
+    // only the blog is implicated — headline/linkedin must NOT be offered as jumps
+    expect(c.locations).toEqual([{ field: 'blog', matches: ['revolutionary'] }]);
+  });
+
+  it('reports one location per implicated field when hype spans several', () => {
+    const checks = runContentChecks({
+      headline: 'groundbreaking news',
+      blog: 'a revolutionary idea',
+    });
+    const c = find(checks, 'no-hype')!;
+    expect(c.locations).toEqual([
+      { field: 'headline', matches: ['groundbreaking'] },
+      { field: 'blog', matches: ['revolutionary'] },
+    ]);
+    // detail stays the flat human sentence across all fields
+    expect(c.detail).toBe('revolutionary, groundbreaking');
+  });
+
+  it('highlights unapproved sources by URL, not bare host, so the span exists in the text', () => {
+    const checks = runContentChecks(
+      { sources: 'https://good.com/a https://reddit.com/r/x' },
+      { approvedHosts: ['good.com'] },
+    );
+    const c = find(checks, 'approved-sources')!;
+    expect(c.status).toBe('fail');
+    expect(c.locations).toEqual([{ field: 'sources', matches: ['https://reddit.com/r/x'] }]);
+    // the approved URL is not offered for highlight
+    expect(c.locations![0].matches).not.toContain('https://good.com/a');
+  });
+
+  it('locates the sources field when there are no sources to check', () => {
+    const checks = runContentChecks({ sources: '' }, { approvedHosts: ['good.com'] });
+    const c = find(checks, 'approved-sources')!;
+    expect(c.status).toBe('warn');
+    expect(c.locations).toEqual([{ field: 'sources' }]);
+  });
+
+  it('every non-passing check carries a location a UI can act on', () => {
+    const checks = runContentChecks(
+      { blog: words(10), linkedin: 'revolutionary', tags: 'a', sources: 'https://reddit.com/x' },
+      { approvedHosts: ['good.com'] },
+    );
+    const stranded = checks.filter((c) => c.status !== 'pass' && !c.locations?.length).map((c) => c.id);
+    // name the offenders — a bare toBeTruthy() would just say "expected truthy"
+    expect(stranded).toEqual([]);
+    expect(checks.some((c) => c.status !== 'pass')).toBe(true);
+  });
+});

package/src/components/validation/checks.ts

@@ -15,6 +15,22 @@
 /** A single check's outcome. Green / amber / red, encoded redundantly in the UI. */
 export type CheckStatus = 'pass' | 'warn' | 'fail';
 
+/**
+ * Where a check's problem lives, so a reviewer UI can jump straight to it
+ * (768w.16.15.3) instead of making the reader hunt for what "7/8" means.
+ */
+export interface CheckLocation {
+  /** The offending field — lets a UI open the right channel/tab first. */
+  field: keyof ContentFields;
+  /**
+   * Exact substrings to highlight within that field, in the order the check
+   * found them. Omitted when the whole field IS the problem (a word count is
+   * not a span), so `matches === undefined` means "jump to the field, don't
+   * highlight anything inside it".
+   */
+  matches?: string[];
+}
+
 /** One deterministic check result. */
 export interface ContentCheck {
   /** Stable id for the check (e.g. `blog-words`, `no-hype`). */
@@ -24,6 +40,13 @@ export interface ContentCheck {
   status: CheckStatus;
   /** Short human explanation (e.g. "462 words", "unapproved: reddit.com"). */
   detail?: string;
+  /**
+   * Where the problem is. Present ONLY when the check is not passing — a green
+   * check has nothing to jump to. `no-hype` can span several fields, hence an
+   * array. `detail` stays the human sentence; this is the machine-readable
+   * counterpart of the same finding.
+   */
+  locations?: CheckLocation[];
 }
 
 /**
@@ -123,6 +146,15 @@ function bandStatus(n: number, [min, max]: Band): CheckStatus {
   return n >= min && n <= max ? 'pass' : 'warn';
 }
 
+/**
+ * `locations` for a whole-field problem (word/char counts, a missing
+ * placeholder): the field itself is the finding, so there is no span to
+ * highlight. Passing checks get nothing — there is nowhere to jump to.
+ */
+function fieldLocation(status: CheckStatus, field: keyof ContentFields): Pick<ContentCheck, 'locations'> {
+  return status === 'pass' ? {} : { locations: [{ field }] };
+}
+
 /** Pull http(s) URLs out of a free-text sources string. */
 export function extractUrls(text: string | null | undefined): string[] {
   if (!text) return [];
@@ -159,69 +191,108 @@ export function runContentChecks(fields: ContentFields, config: ContentChecksCon
   // Word-count bands.
   if (fields.headline !== undefined) {
     const n = wordCount(fields.headline);
-    checks.push({ id: 'headline-words', label: 'Headline length', status: bandStatus(n, headlineWords), detail: `${n} words` });
+    const status = bandStatus(n, headlineWords);
+    checks.push({ id: 'headline-words', label: 'Headline length', status, detail: `${n} words`, ...fieldLocation(status, 'headline') });
   }
   if (fields.blog !== undefined) {
     const n = wordCount(fields.blog);
-    checks.push({ id: 'blog-words', label: 'Blog word count', status: bandStatus(n, blogWords), detail: `${n} words` });
+    const status = bandStatus(n, blogWords);
+    checks.push({ id: 'blog-words', label: 'Blog word count', status, detail: `${n} words`, ...fieldLocation(status, 'blog') });
   }
   if (fields.linkedin !== undefined) {
     const n = wordCount(fields.linkedin);
-    checks.push({ id: 'linkedin-words', label: 'LinkedIn word count', status: bandStatus(n, linkedinWords), detail: `${n} words` });
+    const status = bandStatus(n, linkedinWords);
+    checks.push({ id: 'linkedin-words', label: 'LinkedIn word count', status, detail: `${n} words`, ...fieldLocation(status, 'linkedin') });
   }
 
   // Tag count.
   if (fields.tags !== undefined) {
     const n = tagCount(fields.tags);
-    checks.push({ id: 'tags-count', label: 'Tag count', status: bandStatus(n, tagsCount), detail: `${n} tags` });
+    const status = bandStatus(n, tagsCount);
+    checks.push({ id: 'tags-count', label: 'Tag count', status, detail: `${n} tags`, ...fieldLocation(status, 'tags') });
   }
 
   // Meta description length (characters).
   if (fields.metaDescription !== undefined) {
     const len = fields.metaDescription.trim().length;
-    checks.push({ id: 'meta-length', label: 'Meta description length', status: bandStatus(len, metaChars), detail: `${len} chars` });
+    const status = bandStatus(len, metaChars);
+    checks.push({ id: 'meta-length', label: 'Meta description length', status, detail: `${len} chars`, ...fieldLocation(status, 'metaDescription') });
   }
 
   // `[link]` placeholder present in the LinkedIn post.
   if (requireLink && fields.linkedin !== undefined) {
     const has = fields.linkedin.includes('[link]');
+    const status: CheckStatus = has ? 'pass' : 'warn';
     checks.push({
       id: 'link-placeholder',
       label: '[link] placeholder in LinkedIn',
-      status: has ? 'pass' : 'warn',
+      status,
       detail: has ? undefined : 'no [link] found',
+      // The problem is an ABSENCE, so there is no span to highlight — only a
+      // field to open.
+      ...fieldLocation(status, 'linkedin'),
     });
   }
 
   // No hype words — scan headline + blog + linkedin, lowercased.
-  const hasProse = fields.headline !== undefined || fields.blog !== undefined || fields.linkedin !== undefined;
+  const proseFields: Array<[keyof ContentFields, string | undefined]> = [
+    ['headline', fields.headline],
+    ['blog', fields.blog],
+    ['linkedin', fields.linkedin],
+  ];
+  const hasProse = proseFields.some(([, text]) => text !== undefined);
   if (hasProse) {
-    const haystack = [fields.headline, fields.blog, fields.linkedin]
+    const haystack = proseFields
+      .map(([, text]) => text)
       .filter((s): s is string => typeof s === 'string')
       .join('\n')
       .toLowerCase();
     const found = hypeWords.filter((w) => haystack.includes(w.toLowerCase()));
+    // Re-scan per field so a UI can jump to the RIGHT channel: the joined
+    // haystack above tells us a word exists, not which post it's in.
+    const locations: CheckLocation[] = [];
+    if (found.length > 0) {
+      for (const [field, text] of proseFields) {
+        if (typeof text !== 'string') continue;
+        const hay = text.toLowerCase();
+        const matches = found.filter((w) => hay.includes(w.toLowerCase()));
+        if (matches.length > 0) locations.push({ field, matches });
+      }
+    }
     checks.push({
       id: 'no-hype',
       label: 'No hype words',
       status: found.length > 0 ? 'fail' : 'pass',
       detail: found.length > 0 ? found.join(', ') : undefined,
+      ...(locations.length > 0 ? { locations } : {}),
     });
   }
 
   // Approved sources — only when the app supplied an allow-list.
   if (approvedHosts !== undefined) {
     const approved = new Set(approvedHosts.map((h) => h.toLowerCase().replace(/^www\./, '')));
-    const hosts = extractUrls(fields.sources).map(hostOf).filter(Boolean);
+    const urls = extractUrls(fields.sources);
+    const hosts = urls.map(hostOf).filter(Boolean);
     if (hosts.length === 0) {
-      checks.push({ id: 'approved-sources', label: 'Approved sources', status: 'warn', detail: 'no sources to check' });
+      checks.push({
+        id: 'approved-sources',
+        label: 'Approved sources',
+        status: 'warn',
+        detail: 'no sources to check',
+        locations: [{ field: 'sources' }],
+      });
     } else {
       const bad = Array.from(new Set(hosts.filter((h) => !approved.has(h) || FORUM_SOCIAL.test(h))));
+      // Highlight the offending URLs as they appear in the sources text — the
+      // reviewer pastes URLs, not bare hosts, so matching on the host alone
+      // would highlight nothing.
+      const badUrls = urls.filter((u) => bad.includes(hostOf(u)));
       checks.push({
         id: 'approved-sources',
         label: 'Approved sources',
         status: bad.length > 0 ? 'fail' : 'pass',
         detail: bad.length > 0 ? `unapproved: ${bad.join(', ')}` : `${hosts.length} source${hosts.length === 1 ? '' : 's'} ok`,
+        ...(bad.length > 0 ? { locations: [{ field: 'sources' as const, matches: badUrls }] } : {}),
       });
     }
   }

package/src/components/validation/index.ts

@@ -21,6 +21,7 @@ export {
   hostOf,
   DEFAULT_HYPE_WORDS,
   type ContentCheck,
+  type CheckLocation,
   type ContentFields,
   type ContentChecksConfig,
   type CheckStatus,