@elabs-ai/components-editor 4.0.0

package/src/ai-objects/decision-card.tsx

@@ -0,0 +1,178 @@
+"use client";
+
+/**
+ * DecisionCard — renders a `:::decision{status=accepted date=2026-06-15}` directive
+ * as a decision-record card.
+ *
+ * Anatomy:
+ *   - Status badge (accepted | rejected | proposed | superseded) in a header rail.
+ *   - Date (ISO or human-readable) rendered as a `<time>` element.
+ *   - Rationale body (the directive body text, rendered children).
+ *   - Optional "Alternatives considered" section (comma-separated `alternatives=`
+ *     attribute). The attribute shape is intentional: alternatives are typically
+ *     short phrases, and keeping them out of the body lets the body stay prose.
+ *
+ * Status → Badge variant mapping:
+ *   accepted → success · rejected → destructive · proposed → info ·
+ *   superseded → secondary (neutral — de-emphasized, not a failure).
+ *
+ * The card is a `<section aria-label>` for landmark navigation.
+ */
+import {
+  Badge,
+  Card,
+  CardContent,
+  CardHeader,
+  Separator,
+  type BadgeProps,
+} from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { cva } from "class-variance-authority";
+import { CheckCircle2, CircleDashed, Clock, RefreshCw } from "lucide-react";
+import {
+  forwardRef,
+  type ComponentType,
+  type HTMLAttributes,
+  type ReactNode,
+  type SVGProps,
+} from "react";
+
+/* ------------------------------------------------------------------ */
+/* Status vocabulary                                                    */
+/* ------------------------------------------------------------------ */
+
+export const DECISION_STATUSES = ["accepted", "rejected", "proposed", "superseded"] as const;
+export type DecisionStatus = (typeof DECISION_STATUSES)[number];
+
+const STATUS_BADGE_VARIANT: Record<DecisionStatus, BadgeProps["variant"]> = {
+  accepted: "success",
+  rejected: "destructive",
+  proposed: "info",
+  superseded: "secondary",
+};
+
+const STATUS_LABELS: Record<DecisionStatus, string> = {
+  accepted: "Accepted",
+  rejected: "Rejected",
+  proposed: "Proposed",
+  superseded: "Superseded",
+};
+
+const STATUS_ICONS: Record<DecisionStatus, ComponentType<SVGProps<SVGSVGElement>>> = {
+  accepted: CheckCircle2,
+  rejected: CircleDashed,
+  proposed: Clock,
+  superseded: RefreshCw,
+};
+
+function isDecisionStatus(s: string): s is DecisionStatus {
+  return DECISION_STATUSES.includes(s as DecisionStatus);
+}
+
+/* ------------------------------------------------------------------ */
+/* cva (status rail accent)                                             */
+/* ------------------------------------------------------------------ */
+
+export const decisionCardVariants = cva("border-s-4", {
+  variants: {
+    status: {
+      accepted: "border-s-success",
+      rejected: "border-s-destructive",
+      proposed: "border-s-info",
+      superseded: "border-s-border",
+    },
+  },
+  defaultVariants: { status: "proposed" },
+});
+
+/* ------------------------------------------------------------------ */
+/* Component                                                            */
+/* ------------------------------------------------------------------ */
+
+export interface DecisionCardProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * Decision outcome. One of the four canonical states; anything unrecognised
+   * renders as "proposed".
+   */
+  status?: string;
+  /**
+   * ISO date or human-readable date of the decision
+   * (e.g. `"2026-06-15"` or `"June 2026"`).
+   */
+  date?: string;
+  /**
+   * Comma-separated alternative options considered before this decision.
+   * E.g. `"Redis cache, in-memory map, SQLite"`.
+   */
+  alternatives?: string;
+  /** The rationale body (rendered markdown children of the directive). */
+  children?: ReactNode;
+}
+
+export const DecisionCard = forwardRef<HTMLElement, DecisionCardProps>(function DecisionCard(
+  { status: rawStatus, date, alternatives, children, className, ...props },
+  ref,
+) {
+  const status: DecisionStatus = isDecisionStatus(rawStatus ?? "")
+    ? (rawStatus as DecisionStatus)
+    : "proposed";
+  const badgeVariant = STATUS_BADGE_VARIANT[status];
+  const label = STATUS_LABELS[status];
+  const Icon = STATUS_ICONS[status];
+
+  const altItems = alternatives
+    ? alternatives
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : [];
+
+  return (
+    <section
+      ref={ref}
+      aria-label={`Decision: ${label}`}
+      className={cn("not-prose", className)}
+      {...props}
+    >
+      <Card className={cn(decisionCardVariants({ status }))}>
+        <CardHeader className="pb-3">
+          <div className="flex flex-wrap items-center gap-2">
+            <Badge variant={badgeVariant} className="gap-1.5">
+              <Icon className="size-3" aria-hidden="true" />
+              {label}
+            </Badge>
+            {date ? (
+              <time dateTime={date} className="text-meta text-muted-foreground tabular-nums">
+                {date}
+              </time>
+            ) : null}
+          </div>
+        </CardHeader>
+
+        {children ? (
+          <CardContent className="text-body text-foreground">{children}</CardContent>
+        ) : null}
+
+        {altItems.length > 0 ? (
+          <>
+            <Separator />
+            <div className="px-6 py-4">
+              <p className="mb-2 text-meta font-medium text-muted-foreground">
+                Alternatives considered
+              </p>
+              <ul className="flex flex-wrap gap-1.5" aria-label="Alternatives considered">
+                {altItems.map((alt) => (
+                  <li key={alt}>
+                    <Badge variant="outline" className="text-meta">
+                      {alt}
+                    </Badge>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          </>
+        ) : null}
+      </Card>
+    </section>
+  );
+});

package/src/ai-objects/directives.ts

@@ -0,0 +1,136 @@
+/**
+ * Directive renderer factories for the ai-objects trio.
+ *
+ * Each factory returns a `MarkdownDirectiveRenderer` for registration on
+ * `MarkdownPreview` via the `extensions.directives` prop. The factories are
+ * thin wrappers: they pass directive context into the standalone presentational
+ * components — the library renders, the consumer computes.
+ *
+ * Usage:
+ *   import { aiObjectDirectives } from "@elabs-ai/components-editor/markdown";
+ *
+ *   <MarkdownPreview
+ *     extensions={{ directives: aiObjectDirectives({ resolveKnowledge }) }}
+ *   />
+ */
+import { createElement } from "react";
+
+import type { MarkdownDirectiveRenderer } from "../lib/markdown/directives";
+import { DecisionCard } from "./decision-card";
+import { EntityCard, EntityChip } from "./entity";
+import { KnowledgeCard, type KnowledgeSourceResolver } from "./knowledge-card";
+
+/* ------------------------------------------------------------------ */
+/* Individual factories                                                 */
+/* ------------------------------------------------------------------ */
+
+/**
+ * `decisionDirective()` — registers the `:::decision` container renderer.
+ *
+ * Authoring shape:
+ *   :::decision{status=accepted date=2026-06-15 alternatives="Redis, SQLite"}
+ *   We chose PostgreSQL because it already runs in prod.
+ *   :::
+ */
+export function decisionDirective(): MarkdownDirectiveRenderer {
+  return {
+    name: "decision",
+    kinds: ["container"],
+    render({ attributes, children }) {
+      return createElement(DecisionCard, {
+        status: attributes.status,
+        date: attributes.date,
+        alternatives: attributes.alternatives,
+        children,
+      });
+    },
+  };
+}
+
+/**
+ * `entityDirective()` — registers the `entity` directive for BOTH container
+ * (block card) and inline (chip) syntaxes.
+ *
+ * Authoring shapes:
+ *   Container: :::entity{kind=org name="Acme Corp"}
+ *              Acme Corp is the primary vendor.
+ *              :::
+ *   Inline:    :entity[Acme Corp]{kind=org}
+ */
+export function entityDirective(): MarkdownDirectiveRenderer {
+  return {
+    name: "entity",
+    kinds: ["container", "inline"],
+    render({ kind, attributes, children, textValue }) {
+      if (kind === "inline") {
+        // `textValue` is the verbatim label text (markdown chars preserved);
+        // fall back to rendered children when positions were unavailable.
+        const label = textValue ?? (typeof children === "string" ? children : undefined);
+        return createElement(EntityChip, { kind: attributes.kind, children: label ?? children });
+      }
+      // Container → EntityCard (block)
+      return createElement(EntityCard, {
+        kind: attributes.kind,
+        name: attributes.name,
+        children,
+      });
+    },
+  };
+}
+
+/**
+ * `knowledgeDirective({ resolve })` — registers the `:::knowledge` container
+ * renderer. The `resolve` hook is consumer-supplied; omitting it causes all
+ * sources to render as plain unlinked labels (safe default).
+ *
+ * Authoring shape:
+ *   :::knowledge{sources="notes/a.md, notes/b.md"}
+ *   PostgreSQL was chosen because …
+ *   :::
+ */
+export function knowledgeDirective(options?: {
+  resolve?: KnowledgeSourceResolver;
+}): MarkdownDirectiveRenderer {
+  return {
+    name: "knowledge",
+    kinds: ["container"],
+    render({ attributes, children }) {
+      return createElement(KnowledgeCard, {
+        sources: attributes.sources,
+        resolve: options?.resolve,
+        children,
+      });
+    },
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* Convenience bundle                                                   */
+/* ------------------------------------------------------------------ */
+
+export interface AiObjectDirectivesOptions {
+  /** Consumer-supplied resolver for `:::knowledge` source paths. */
+  resolveKnowledge?: KnowledgeSourceResolver;
+}
+
+/**
+ * `aiObjectDirectives(options)` — returns all three directive renderers as an
+ * array ready to pass to `extensions.directives`:
+ *   - `decisionDirective()`
+ *   - `entityDirective()`
+ *   - `knowledgeDirective({ resolve: options.resolveKnowledge })`
+ *
+ * @example
+ *   <MarkdownPreview
+ *     extensions={{ directives: aiObjectDirectives({ resolveKnowledge }) }}
+ *   />
+ */
+export function aiObjectDirectives(
+  options: AiObjectDirectivesOptions = {},
+): MarkdownDirectiveRenderer[] {
+  return [
+    decisionDirective(),
+    entityDirective(),
+    knowledgeDirective({ resolve: options.resolveKnowledge }),
+  ];
+}

package/src/ai-objects/entity.tsx

@@ -0,0 +1,181 @@
+"use client";
+
+/**
+ * EntityCard + EntityChip — renders `:::entity{kind=org name="Acme"}` (block card)
+ * and `:entity[Acme]{kind=org}` (inline chip) directives.
+ *
+ * One component handles both syntaxes; the renderer factory branches on `ctx.kind`.
+ *
+ * Entity kinds and their icon/tone:
+ *   org     → Building2 / secondary (companies, organisations)
+ *   person  → User      / primary (people, authors)
+ *   place   → MapPin    / info    (locations, regions)
+ *   product → Box       / success (products, services)
+ *   concept → Lightbulb / warning (ideas, topics)
+ *   default → Tag       / outline (anything else)
+ *
+ * The inline chip is a `<span>` — no block wrapper — so it stays inside `<p>` without
+ * creating invalid HTML. A11y: kind is conveyed via `aria-label` (not icon alone).
+ */
+import { Card, CardContent, CardHeader, CardTitle } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { cva, type VariantProps } from "class-variance-authority";
+import { Box, Building2, Lightbulb, MapPin, Tag, User } from "lucide-react";
+import {
+  forwardRef,
+  type ComponentType,
+  type HTMLAttributes,
+  type ReactNode,
+  type SVGProps,
+} from "react";
+
+/* ------------------------------------------------------------------ */
+/* Kind vocabulary                                                      */
+/* ------------------------------------------------------------------ */
+
+export const ENTITY_KINDS = ["org", "person", "place", "product", "concept"] as const;
+export type EntityKind = (typeof ENTITY_KINDS)[number];
+
+type KindMeta = {
+  Icon: ComponentType<SVGProps<SVGSVGElement>>;
+  label: string;
+};
+
+const KIND_META: Record<string, KindMeta> = {
+  org: { Icon: Building2, label: "Organisation" },
+  person: { Icon: User, label: "Person" },
+  place: { Icon: MapPin, label: "Place" },
+  product: { Icon: Box, label: "Product" },
+  concept: { Icon: Lightbulb, label: "Concept" },
+};
+
+const DEFAULT_KIND_META: KindMeta = { Icon: Tag, label: "Entity" };
+
+function kindMeta(kind: string | undefined): KindMeta {
+  return KIND_META[kind ?? ""] ?? DEFAULT_KIND_META;
+}
+
+/* ------------------------------------------------------------------ */
+/* cva                                                                  */
+/* ------------------------------------------------------------------ */
+
+export const entityChipVariants = cva(
+  // inline-flex + align-middle keeps the chip in the text baseline;
+  // no `block` wrapper so it is valid inside <p>.
+  "inline-flex items-center gap-1 rounded-sm border px-1.5 py-0.5 text-meta font-medium align-middle focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+  {
+    variants: {
+      kind: {
+        org: "border-border bg-secondary/60 text-secondary-foreground",
+        // #399 — same reasoning as `concept` below: a 10% WASH is not a plate
+        // and not a mark, so the LABEL takes the on-surface `-text` rung. This
+        // is the row that had no `-text` rung to reach for until #399 minted it.
+        person: "border-primary/30 bg-primary/10 text-primary-text",
+        place: "border-info/30 bg-info/10 text-info-text",
+        product: "border-success/30 bg-success/10 text-success-text",
+        // `-text`, not `-foreground`: the chip is a 10% WASH on the page surface,
+        // not a solid `--warning` plate, so it needs the on-surface rung its
+        // place/product siblings use (#381 flipped `--warning-foreground` to
+        // light ink for the now-deep fill).
+        concept: "border-warning/30 bg-warning/10 text-warning-text",
+        default: "border-border text-foreground",
+      },
+    },
+    defaultVariants: { kind: "default" },
+  },
+);
+
+function chipKind(kind: string | undefined): VariantProps<typeof entityChipVariants>["kind"] {
+  if (!kind) return "default";
+  const known: Array<VariantProps<typeof entityChipVariants>["kind"]> = [
+    "org",
+    "person",
+    "place",
+    "product",
+    "concept",
+    "default",
+  ];
+  return known.includes(kind as never)
+    ? (kind as VariantProps<typeof entityChipVariants>["kind"])
+    : "default";
+}
+
+/* ------------------------------------------------------------------ */
+/* EntityChip (inline)                                                  */
+/* ------------------------------------------------------------------ */
+
+export interface EntityChipProps extends HTMLAttributes<HTMLSpanElement> {
+  /** Entity kind — drives icon and tone. */
+  kind?: string;
+  /** Display label (the directive's label text or `name` attribute). */
+  children?: ReactNode;
+}
+
+export const EntityChip = forwardRef<HTMLSpanElement, EntityChipProps>(function EntityChip(
+  { kind: rawKind, children, className, ...props },
+  ref,
+) {
+  const { Icon, label } = kindMeta(rawKind);
+  const resolvedKind = chipKind(rawKind);
+  return (
+    <span
+      ref={ref}
+      role="mark"
+      aria-label={children ? `${String(children)} (${label})` : label}
+      className={cn(entityChipVariants({ kind: resolvedKind }), className)}
+      {...props}
+    >
+      <Icon className="size-3 shrink-0" aria-hidden="true" />
+      <span>{children}</span>
+    </span>
+  );
+});
+
+/* ------------------------------------------------------------------ */
+/* EntityCard (block)                                                   */
+/* ------------------------------------------------------------------ */
+
+export interface EntityCardProps extends HTMLAttributes<HTMLElement> {
+  /** Entity kind — drives the icon and header tone. */
+  kind?: string;
+  /** Entity name. Falls back to children when absent. */
+  name?: string;
+  /** Description body (rendered markdown children of the directive). */
+  children?: ReactNode;
+}
+
+export const EntityCard = forwardRef<HTMLElement, EntityCardProps>(function EntityCard(
+  { kind: rawKind, name, children, className, ...props },
+  ref,
+) {
+  const { Icon, label } = kindMeta(rawKind);
+
+  return (
+    <section
+      ref={ref}
+      aria-label={name ? `${label}: ${name}` : label}
+      className={cn("not-prose", className)}
+      {...props}
+    >
+      <Card>
+        <CardHeader className="pb-3">
+          <div className="flex items-center gap-2">
+            <span
+              className="flex size-7 shrink-0 items-center justify-center rounded-md bg-muted"
+              aria-hidden="true"
+            >
+              <Icon className="size-4 text-muted-foreground" />
+            </span>
+            <div className="min-w-0">
+              {name ? <CardTitle className="truncate">{name}</CardTitle> : null}
+              <p className="text-meta text-muted-foreground">{label}</p>
+            </div>
+          </div>
+        </CardHeader>
+        {children ? (
+          <CardContent className="text-body text-foreground">{children}</CardContent>
+        ) : null}
+      </Card>
+    </section>
+  );
+});

package/src/ai-objects/index.ts

@@ -0,0 +1,34 @@
+// Presentational components — usable standalone or composed by the directive factories.
+export {
+  DecisionCard,
+  decisionCardVariants,
+  DECISION_STATUSES,
+  type DecisionCardProps,
+  type DecisionStatus,
+} from "./decision-card";
+
+export {
+  EntityCard,
+  EntityChip,
+  entityChipVariants,
+  ENTITY_KINDS,
+  type EntityCardProps,
+  type EntityChipProps,
+  type EntityKind,
+} from "./entity";
+
+export {
+  KnowledgeCard,
+  type KnowledgeCardProps,
+  type KnowledgeSourceResolved,
+  type KnowledgeSourceResolver,
+} from "./knowledge-card";
+
+// Directive renderer factories — wire these into MarkdownPreview `extensions.directives`.
+export {
+  decisionDirective,
+  entityDirective,
+  knowledgeDirective,
+  aiObjectDirectives,
+  type AiObjectDirectivesOptions,
+} from "./directives";

package/src/ai-objects/knowledge-card.tsx

@@ -0,0 +1,143 @@
+"use client";
+
+/**
+ * KnowledgeCard — renders a `:::knowledge{sources="notes/a.md, notes/b.md"}` directive
+ * as a sourced-fact card.
+ *
+ * Anatomy:
+ *   - Fact body (rendered markdown children of the directive).
+ *   - Sources section: each comma-split path is handed to the consumer's `resolve`
+ *     hook (`resolve(path) => { href, title } | null`). Resolved paths render as
+ *     `<a>` links; unresolved paths render as plain `<span>` labels — graceful
+ *     degradation, no errors thrown.
+ *
+ * The library never reads files. Domain logic (vault index, file system, API) lives
+ * entirely in the consumer's `resolve` hook — the same principle as `resolveUrl` on
+ * `MarkdownPreview` and `evaluate` on calc blocks.
+ *
+ * `KnowledgeCard` is standalone (no `resolve` → sources rendered as plain labels).
+ * The `knowledgeDirective({ resolve })` factory wires the hook for directive use.
+ */
+import { Card, CardContent, CardFooter } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { BookOpen, FileText } from "lucide-react";
+import { forwardRef, type HTMLAttributes, type ReactNode } from "react";
+
+/* ------------------------------------------------------------------ */
+/* Resolver type (consumer-supplied; never bundled)                     */
+/* ------------------------------------------------------------------ */
+
+export interface KnowledgeSourceResolved {
+  href: string;
+  title?: string;
+}
+
+/**
+ * Consumer-supplied resolver: path → link data, or `null` when the path cannot
+ * be resolved (stale vault link, missing file, etc.). The card degrades
+ * gracefully — the source renders as a plain label rather than a broken link.
+ */
+export type KnowledgeSourceResolver = (path: string) => KnowledgeSourceResolved | null;
+
+/* ------------------------------------------------------------------ */
+/* Sub-component: a single resolved/unresolved source row               */
+/* ------------------------------------------------------------------ */
+
+interface SourceRowProps {
+  path: string;
+  resolve?: KnowledgeSourceResolver;
+}
+
+function SourceRow({ path, resolve }: SourceRowProps) {
+  const resolved = resolve ? resolve(path) : null;
+  const display = resolved?.title ?? path;
+
+  if (resolved) {
+    return (
+      <a
+        href={resolved.href}
+        rel="noopener noreferrer"
+        target="_blank"
+        // #399 — a source link is TEXT: on-surface `-text` rung, not the fill.
+        className="flex min-w-0 items-center gap-1.5 text-meta text-primary-text underline-offset-2 hover:underline focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+        aria-label={`Source: ${display}`}
+      >
+        <FileText className="size-3 shrink-0" aria-hidden="true" />
+        <span className="truncate">{display}</span>
+      </a>
+    );
+  }
+
+  return (
+    <span
+      className="flex min-w-0 items-center gap-1.5 text-meta text-muted-foreground"
+      aria-label={`Source (unresolved): ${display}`}
+    >
+      <FileText className="size-3 shrink-0" aria-hidden="true" />
+      <span className="truncate">{display}</span>
+    </span>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/* KnowledgeCard                                                        */
+/* ------------------------------------------------------------------ */
+
+export interface KnowledgeCardProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * Comma-separated source paths (e.g. `"notes/a.md, notes/b.md"`).
+   * Each path is handed to `resolve`; unresolved paths render as plain labels.
+   */
+  sources?: string;
+  /**
+   * Consumer-supplied resolver. `undefined` → all sources render as plain labels
+   * (safe default — never throws, never reads files).
+   */
+  resolve?: KnowledgeSourceResolver;
+  /** The fact body (rendered markdown children of the directive). */
+  children?: ReactNode;
+}
+
+export const KnowledgeCard = forwardRef<HTMLElement, KnowledgeCardProps>(function KnowledgeCard(
+  { sources, resolve, children, className, ...props },
+  ref,
+) {
+  const sourcePaths = sources
+    ? sources
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : [];
+
+  return (
+    <section
+      ref={ref}
+      aria-label="Knowledge fact"
+      className={cn("not-prose", className)}
+      {...props}
+    >
+      <Card className="border-s-4 border-s-info">
+        <CardContent className="pt-4">
+          <div className="mb-2 flex items-center gap-1.5">
+            <BookOpen className="size-3.5 shrink-0 text-info-text" aria-hidden="true" />
+            <span className="text-meta font-medium text-info-text">Knowledge</span>
+          </div>
+          <div className="text-body text-foreground">{children}</div>
+        </CardContent>
+
+        {sourcePaths.length > 0 ? (
+          <CardFooter className="flex-col items-start gap-1 border-t border-border pt-3">
+            <p className="text-meta font-medium text-muted-foreground">Sources</p>
+            <ul className="flex w-full flex-col gap-1" aria-label="Sources">
+              {sourcePaths.map((path) => (
+                <li key={path} className="min-w-0">
+                  <SourceRow path={path} resolve={resolve} />
+                </li>
+              ))}
+            </ul>
+          </CardFooter>
+        ) : null}
+      </Card>
+    </section>
+  );
+});