@immediately-run/grove 0.1.10 → 0.2.2

package/src/lib/navigationPolicy.ts

@@ -0,0 +1,57 @@
+// The navigation policy (APP_CUSTOMIZATION_SPEC §4.3, R3-872) — every in-bundle entry
+// link's plain click goes through ONE replaceable function, so a shell that composes
+// GroveEntry decides what "follow" means (route, open elsewhere, intercept) without
+// forking a component.
+//
+// This file exports no component (the Fast-Refresh rule), so the context lives here
+// beside the default it falls back to.
+
+import { createContext } from 'react';
+import { navigate } from '@immediately-run/sdk';
+
+/** A resolved link target: the corpus key, any `#fragment`, the concrete href the
+ *  anchor already renders (modifier-/middle-click still open it in a new tab), and
+ *  the entry the link was rendered inside (`from`). Resolution happens at the call
+ *  site — the policy receives the ANSWER, never a string to re-derive. */
+export interface FollowLinkTarget {
+  key: string;
+  fragment?: string;
+  href: string;
+  from?: string;
+}
+
+/** What a plain click on an entry link does. */
+export type FollowLink = (target: FollowLinkTarget) => void;
+
+/** The stock behaviour: navigate to the resolved href, exactly as the SDK's Link
+ *  would have. */
+export const defaultFollowLink: FollowLink = ({ href }) => navigate(href);
+
+/**
+ * The active policy. Read via `useFollowLink()` (the hook file keeps the
+ * component-tree rule); the context's default is the stock behaviour, so an
+ * unprovided tree behaves exactly as before (R-CUST-2).
+ */
+export const NavigationPolicyContext = createContext<FollowLink>(defaultFollowLink);
+
+/**
+ * The anchor `onClick` half of the policy (R-CUST-3): a PLAIN click (no modifier,
+ * primary button) goes to the policy and never to the browser; a modified click
+ * falls through to the anchor's real `href` (new tab/window semantics are the
+ * browser's, and an anchor that lost them is a bug). A policy that throws is caught,
+ * logged with the target, and NOT silently fallen back from (R-CUST-5: fail loudly).
+ */
+export function followLinkOnClick(
+  follow: FollowLink,
+  target: FollowLinkTarget,
+): (e: { button: number; metaKey: boolean; ctrlKey: boolean; shiftKey: boolean; altKey: boolean; preventDefault: () => void }) => void {
+  return (e) => {
+    if (e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+    e.preventDefault();
+    try {
+      follow(target);
+    } catch (err) {
+      console.error(`[grove] the navigation policy threw for ${target.key}${target.fragment ?? ''}`, err);
+    }
+  };
+}

package/src/lib/renderMode.ts

@@ -0,0 +1,17 @@
+// The safe-vs-compiled render decision, in ONE place (R3-872 review, round 1):
+// interpreter mode is read from the HOME entry (wiki-wide) OR the current entry
+// (per-entry), and the two answer different questions — wiki-wide is the
+// interpreter declaration for foreign content; per-entry exists for the document
+// that is only correct as data (R3-252's proof page). Three renderers decide on
+// this — the layout chain's renderer pick, the entry body's pick, and the shell's
+// `safe` field — and drift between them is a trust-boundary hole (an executing
+// body inside a safe chain), never a style issue. Pure, so the rule is testable
+// without a render.
+
+/** True when the entry renders through the non-executable interpreter path. */
+export function resolveSafeRender(
+  homeMeta: Record<string, unknown> | null | undefined,
+  entryMeta: Record<string, unknown> | null | undefined,
+): boolean {
+  return homeMeta?.render === 'safe' || entryMeta?.render === 'safe';
+}

package/src/lib/shell.ts

@@ -67,6 +67,10 @@ export interface GroveShell {
    *  `checking` while the readdir is in flight — <PageView> must render neither the
    *  entry nor the 404 then, or a folder URL flashes "No entry at …" before healing. */
   directory: DirectoryListing;
+  /** R3-872 — the entry frame's gate input: the content stylesheets' read state.
+   *  Wiki-wide (the home entry's declaration), provided by the engine root;
+   *  standalone compositions default to 'ready' (no sheets declared). */
+  stylesheetsStatus?: 'loading' | 'ready';
 }
 
 /** The refusal sentence, ONE home (R6, R3-608): every surface that offers an edit

package/src/lib/tagCloud.test.ts

@@ -0,0 +1,115 @@
+// countTags / tagWeight / topTags — the pure half of TagCloud. The counting case
+// runs over the repo's REAL content tree, parsed with the real frontmatter parser,
+// so a drifted fixture cannot agree with the code by accident (ways_of_working §4).
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { parseFrontmatter } from './frontmatter';
+import { countTags, tagWeight, topTags, type TagCount } from './tagCloud';
+
+const CONTENT_ROOT = '/app/content/';
+
+/** Every .mdx under the repo's content/ as a metadata map keyed the way the
+ *  store keys it (absolute module path under the app root). */
+const realCorpusMetadata = (): Record<string, { tags?: unknown }> => {
+  const dir = join(process.cwd(), 'content');
+  const walk = (d: string): string[] =>
+    readdirSync(d, { withFileTypes: true }).flatMap((e) =>
+      e.isDirectory() ? walk(join(d, e.name)) : e.name.endsWith('.mdx') ? [join(d, e.name)] : [],
+    );
+  const files: Record<string, { tags?: unknown }> = {};
+  for (const abs of walk(dir)) {
+    const { data } = parseFrontmatter(readFileSync(abs, 'utf8'));
+    files[CONTENT_ROOT + abs.slice(dir.length + 1)] = { tags: (data as { tags?: unknown }).tags };
+  }
+  return files;
+};
+
+/** The same count, computed independently in the test from the same parsed map. */
+const expectCounts = (files: Record<string, { tags?: unknown }>): TagCount[] => {
+  const counts = new Map<string, number>();
+  for (const [p, m] of Object.entries(files)) {
+    if (!p.startsWith(CONTENT_ROOT)) continue;
+    for (const t of Array.isArray(m.tags) ? (m.tags as string[]) : []) {
+      if (t.startsWith('ui/')) continue;
+      counts.set(t, (counts.get(t) ?? 0) + 1);
+    }
+  }
+  return [...counts.keys()].sort().map((tag) => ({ tag, count: counts.get(tag)! }));
+};
+
+describe('countTags', () => {
+  it('over the real corpus, equals the independent count and carries no ui/ tag', () => {
+    const files = realCorpusMetadata();
+    expect(Object.keys(files).length).toBeGreaterThan(0);
+    const result = countTags(files, CONTENT_ROOT);
+    expect(result).toEqual(expectCounts(files));
+    expect(result.some(({ tag }) => tag.startsWith('ui/'))).toBe(false);
+  });
+
+  it('ignores entries outside the content root and non-array tags', () => {
+    const result = countTags(
+      {
+        '/app/content/a.mdx': { tags: ['x'] },
+        '/other/b.mdx': { tags: ['x'] },
+        '/app/content/c.mdx': { tags: 'x' },
+        '/app/content/d.mdx': null,
+      },
+      CONTENT_ROOT,
+    );
+    expect(result).toEqual([{ tag: 'x', count: 1 }]);
+  });
+});
+
+describe('tagWeight', () => {
+  it('gives the minimum 0 and the maximum 1', () => {
+    expect(tagWeight(1, 1, 191)).toBe(0);
+    expect(tagWeight(191, 1, 191)).toBe(1);
+  });
+
+  it('is strictly increasing over the real corpus spread (1, 15, 191)', () => {
+    const w = [1, 15, 191].map((c) => tagWeight(c, 1, 191));
+    expect(w[0]!).toBeLessThan(w[1]!);
+    expect(w[1]!).toBeLessThan(w[2]!);
+    // Logarithmic: a tag 15x the minimum sits well under the arithmetic midpoint.
+    expect(w[1]!).toBeLessThan(0.6);
+  });
+
+  it('clamps a count beyond the range', () => {
+    expect(tagWeight(10_000, 1, 191)).toBe(1);
+  });
+
+  it('returns 0 when there is no spread (one tag, or all equal)', () => {
+    expect(tagWeight(7, 7, 7)).toBe(0);
+  });
+
+  it('returns 0 for a count below 1 or a non-finite count', () => {
+    expect(tagWeight(0, 1, 10)).toBe(0);
+    expect(tagWeight(Number.NaN, 1, 10)).toBe(0);
+  });
+});
+
+describe('topTags', () => {
+  const five: TagCount[] = [
+    { tag: 'alpha', count: 3 },
+    { tag: 'beta', count: 9 },
+    { tag: 'gamma', count: 12 },
+    { tag: 'delta', count: 12 },
+    { tag: 'epsilon', count: 1 },
+  ];
+
+  it('keeps the N highest counts and returns them in tag order', () => {
+    expect(topTags(five, 2).map((t) => t.tag)).toEqual(['delta', 'gamma']);
+  });
+
+  it('breaks a tie at the cut by tag name', () => {
+    // beta(9) and a tie between gamma/delta(12): limit 2 takes delta+gamma; a
+    // tie AT the cut (limit 3 leaves beta out) — add a second 9 to force it.
+    const withTie: TagCount[] = [...five.slice(0, 2), { tag: 'zed', count: 9 }, ...five.slice(2)];
+    expect(topTags(withTie, 3).map((t) => t.tag)).toEqual(['beta', 'delta', 'gamma']);
+  });
+
+  it('returns the input when no limit is given', () => {
+    expect(topTags(five)).toBe(five);
+  });
+});

package/src/lib/tagCloud.ts

@@ -0,0 +1,58 @@
+// TagCloud's counting and scaling, extracted from the component so the cases are
+// unit-testable (the component is a thin wiring shell). The chip's pixel range is
+// NOT here — it lives in GroveApp.css, and the component only hands each chip a
+// 0..1 weight via `--tag-weight`.
+
+/** One tag and how many content entries carry it. */
+export interface TagCount {
+  tag: string;
+  count: number;
+}
+
+interface TaggedMeta {
+  tags?: unknown;
+}
+
+/** Every tag across the corpus with its count, sorted by tag. Only entries under
+ *  the content root count; `ui/` tags are chrome (they drive layout, not
+ *  classification) and are skipped. */
+export function countTags(filesMetadata: Record<string, TaggedMeta | null>, contentRoot: string): TagCount[] {
+  const counts: Record<string, number> = {};
+  Object.entries(filesMetadata).forEach(([p, m]) => {
+    if (!p.startsWith(contentRoot)) return;
+    if (m && Array.isArray(m.tags)) {
+      (m.tags as string[]).forEach((t) => {
+        if (t.startsWith('ui/')) return;
+        counts[t] = (counts[t] || 0) + 1;
+      });
+    }
+  });
+  return Object.keys(counts)
+    .sort()
+    .map((tag) => ({ tag, count: counts[tag]! }));
+}
+
+/** A tag's weight in the closed range 0..1: logarithmic and relative to THIS
+ *  corpus's own minimum and maximum, so the scale holds at 10 entries and at
+ *  10,000 — the least-used tag renders 0, the most-used 1, and a tag used ten
+ *  times as often is visibly but not ten times larger. No spread (`max === min`)
+ *  returns 0, so a uniform corpus renders plain chips; a count below 1 or a
+ *  non-finite count returns 0. */
+export function tagWeight(count: number, min: number, max: number): number {
+  if (!Number.isFinite(count) || count < 1) return 0;
+  if (max <= min) return 0;
+  const w = (Math.log(count) - Math.log(min)) / (Math.log(max) - Math.log(min));
+  return Math.min(1, Math.max(0, w));
+}
+
+/** The `limit` most-used tags, ties at the cut broken by tag name, re-sorted by
+ *  tag for display (the cloud reads alphabetically). An absent limit returns the
+ *  input unchanged — validating a bad limit is the component's job (it warns). */
+export function topTags(entries: TagCount[], limit?: number): TagCount[] {
+  if (limit === undefined) return entries;
+  return entries
+    .slice()
+    .sort((a, b) => b.count - a.count || (a.tag < b.tag ? -1 : a.tag > b.tag ? 1 : 0))
+    .slice(0, limit)
+    .sort((a, b) => (a.tag < b.tag ? -1 : a.tag > b.tag ? 1 : 0));
+}

package/src/lib.ts

@@ -52,3 +52,21 @@ export {
 export { getContentRoot, isDispatched } from './lib/contentRoot';
 export { layoutChainForKey } from './lib/layout';
 export { queryPaths, readingTime, stripFrontmatter } from './lib/wiki';
+
+// The entry composition seam (R3-872, APP_CUSTOMIZATION_SPEC §4.1): render one entry
+// from a key — header + body + metadata + tags — framed by its layout chain or bare,
+// publishing the entry context either way.
+export { default as GroveEntry } from './components/GroveEntry';
+export { useEntryKey } from './hooks/useEntryKey';
+
+// The navigation policy (§4.3): every in-bundle entry link's plain click rides one
+// replaceable function; the href stays real for modifier/middle clicks.
+export { NavigationPolicyContext, defaultFollowLink, followLinkOnClick } from './lib/navigationPolicy';
+export type { FollowLink, FollowLinkTarget } from './lib/navigationPolicy';
+export { useFollowLink } from './hooks/useFollowLink';
+
+// The entry-scoped helpers (§4.5): fragment resolution and heading collection scoped
+// to one entry's marked body.
+export { fragmentOf, resolveFragmentTarget } from './lib/fragment';
+export { useHeadings } from './hooks/useHeadings';
+export type { Heading } from './hooks/useHeadings';