@astryxdesign/core 0.6.2-canary.bfee8a4 → 0.6.2-canary.c8d5849

package/src/Markdown/plugins/frontmatter.test.tsx

@@ -0,0 +1,125 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file frontmatter.test.tsx
+ * @input Native document-start frontmatter in complete and streaming documents
+ * @output Typed metadata, non-rendering, ordering, and failure coverage
+ * @position Acceptance tests for first-party Markdown frontmatter
+ */
+
+import {renderToString} from 'react-dom/server';
+import {describe, expect, expectTypeOf, it} from 'vitest';
+import {Markdown} from '../Markdown';
+import {parseMarkdownAst, parseMarkdownAstInternal} from '../parser';
+import {createMarkdownPlugin, type MarkdownTransform} from './protocol';
+import {createMarkdownFrontmatter} from './frontmatter';
+
+const documentMetadata = createMarkdownFrontmatter({
+  name: 'document-metadata',
+  parse(fields) {
+    return {title: fields.title ?? '', draft: fields.draft === 'true'};
+  },
+});
+
+const SOURCE = '---\ntitle: Release notes\ndraft: true\n---\n# Shipped\n\nBody';
+
+describe('createMarkdownFrontmatter', () => {
+  it('removes document-start syntax and exposes typed metadata to later plugins', () => {
+    let seen: ReturnType<typeof documentMetadata.getMetadata>;
+    const observer = createMarkdownPlugin({
+      name: 'frontmatter-observer',
+      apiVersion: 1,
+      transform(root) {
+        seen = documentMetadata.getMetadata(root);
+        return root;
+      },
+    });
+    const root = parseMarkdownAst(SOURCE, {
+      plugins: [documentMetadata.plugin, observer],
+    });
+
+    expect(seen).toEqual({title: 'Release notes', draft: true});
+    expect(documentMetadata.parse(SOURCE)).toEqual({
+      status: 'match',
+      contentStart: SOURCE.indexOf('# Shipped'),
+      metadata: {title: 'Release notes', draft: true},
+    });
+    expect(documentMetadata.getMetadata(root)).toEqual(seen);
+    expect(root.children).toHaveLength(2);
+    expect(JSON.stringify(root)).not.toContain('title: Release notes');
+    expectTypeOf(documentMetadata.plugin).toMatchTypeOf<{
+      readonly name: string;
+    }>();
+  });
+
+  it('hides unfinished streaming frontmatter and exposes it once closed', () => {
+    const partial = parseMarkdownAstInternal(
+      '---\ntitle: Pending',
+      {plugins: [documentMetadata.plugin]},
+      false,
+    );
+    expect(documentMetadata.getMetadata(partial)).toBeUndefined();
+    expect(partial.children).toEqual([]);
+
+    const settled = parseMarkdownAstInternal(
+      SOURCE,
+      {plugins: [documentMetadata.plugin]},
+      false,
+    );
+    expect(documentMetadata.getMetadata(settled)).toEqual({
+      title: 'Release notes',
+      draft: true,
+    });
+    expect(settled.children[0]).toMatchObject({type: 'heading'});
+    expect(
+      documentMetadata.parse(
+        '---\r\ntitle: Windows\r\ndraft: false\r\n---\r\nBody',
+      ),
+    ).toMatchObject({
+      status: 'match',
+      metadata: {title: 'Windows', draft: false},
+    });
+  });
+
+  it('does not treat non-leading frontmatter syntax as metadata', () => {
+    expect(
+      documentMetadata.getMetadata(
+        parseMarkdownAst(`# Intro\n\n${SOURCE}`, {
+          plugins: [documentMetadata.plugin],
+        }),
+      ),
+    ).toBeUndefined();
+  });
+
+  it('keeps renderer and server output free of metadata syntax', () => {
+    const html = renderToString(
+      <Markdown plugins={[documentMetadata.plugin]}>{SOURCE}</Markdown>,
+    );
+    expect(html).toContain('Shipped');
+    expect(html).toContain('Body');
+    expect(html).not.toContain('Release notes');
+    expect(html).not.toContain('draft');
+  });
+
+  it('rejects duplicate fields and unrepresentable decoded metadata', () => {
+    const duplicate = parseMarkdownAst(
+      '---\ntitle: One\ntitle: Two\n---\nBody',
+      {plugins: [documentMetadata.plugin]},
+    );
+    expect(documentMetadata.getMetadata(duplicate)).toBeUndefined();
+
+    const invalid = createMarkdownFrontmatter({
+      name: 'invalid',
+      parse: () => new Date() as never,
+    });
+    expect(() =>
+      parseMarkdownAst(SOURCE, {plugins: [invalid.plugin]}),
+    ).not.toThrow();
+  });
+
+  it('returns a transform plugin that composes in the ordered pipeline', () => {
+    expectTypeOf<MarkdownTransform>().toBeFunction();
+    const root = parseMarkdownAst(SOURCE, {plugins: [documentMetadata.plugin]});
+    expect(root.children[0]).toMatchObject({type: 'heading', depth: 1});
+  });
+});

package/src/Markdown/plugins/frontmatter.ts

@@ -0,0 +1,198 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file frontmatter.ts
+ * @input Document-start frontmatter delimiters and a typed metadata decoder
+ * @output A Markdown plugin plus a typed metadata reader for later transforms
+ * @position Optional first-party document metadata helper
+ */
+
+import type {MarkdownAstRoot} from '../ast';
+import {
+  createMarkdownPlugin,
+  freezeMarkdownPluginData,
+  isMarkdownPluginData,
+  markMarkdownTransformTrusted,
+  type MarkdownExtensionNode,
+  type MarkdownPluginData,
+  type MarkdownPluginEntry,
+  type MarkdownTransform,
+} from './protocol';
+
+const ENVELOPE_KEY = 'astryx:frontmatter';
+const ENVELOPE_BRAND = 'astryx.markdown.frontmatter';
+const ENVELOPE_VERSION = 1;
+
+type FrontmatterRecord = Readonly<Record<string, string>>;
+type Envelope = {
+  readonly brand: typeof ENVELOPE_BRAND;
+  readonly version: typeof ENVELOPE_VERSION;
+  readonly values: Readonly<Record<string, MarkdownPluginData>>;
+};
+
+export interface MarkdownFrontmatterOptions<
+  Metadata extends MarkdownPluginData,
+> {
+  /** Stable plugin and metadata namespace. */
+  readonly name: string;
+  /** Converts validated key/value fields into typed document metadata. */
+  readonly parse: (fields: FrontmatterRecord) => Metadata;
+}
+
+export type MarkdownFrontmatterParseResult<
+  Metadata extends MarkdownPluginData,
+> =
+  | {readonly status: 'none'}
+  | {readonly status: 'defer'}
+  | {
+      readonly status: 'match';
+      readonly contentStart: number;
+      readonly metadata: Metadata;
+    };
+
+export interface MarkdownFrontmatter<Metadata extends MarkdownPluginData> {
+  readonly plugin: MarkdownPluginEntry<never>;
+  parse(
+    source: string,
+    isFinal?: boolean,
+  ): MarkdownFrontmatterParseResult<Metadata>;
+  getMetadata(
+    document: MarkdownAstRoot<MarkdownExtensionNode>,
+  ): Metadata | undefined;
+}
+
+type DataRecord = Readonly<Record<string, MarkdownPluginData>>;
+
+function asDataRecord(value: MarkdownPluginData | undefined): DataRecord {
+  return value != null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as DataRecord)
+    : {};
+}
+
+function parseEnvelope(value: unknown): Envelope | undefined {
+  if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+    return;
+  }
+  const candidate = value as Partial<Envelope>;
+  return candidate.brand === ENVELOPE_BRAND &&
+    candidate.version === ENVELOPE_VERSION &&
+    candidate.values != null &&
+    typeof candidate.values === 'object' &&
+    !Array.isArray(candidate.values)
+    ? (candidate as Envelope)
+    : undefined;
+}
+
+function readFrontmatter(source: string):
+  | {readonly status: 'none'}
+  | {readonly status: 'defer'}
+  | {
+      readonly status: 'match';
+      readonly end: number;
+      readonly fields: FrontmatterRecord;
+    } {
+  const openingLength = source.startsWith('---\r\n')
+    ? 5
+    : source.startsWith('---\n')
+      ? 4
+      : 0;
+  if (openingLength === 0) {
+    return {status: 'none'};
+  }
+  const body = source.slice(openingLength);
+  const close = /(?:^|\r?\n)---(?=\r?\n|$)/.exec(body);
+  if (close == null) {
+    return {status: 'defer'};
+  }
+  const fields: Record<string, string> = Object.create(null);
+  for (const line of body.slice(0, close.index).split(/\r?\n/)) {
+    if (line.trim() === '') {
+      continue;
+    }
+    const separator = line.indexOf(':');
+    const key = line.slice(0, separator).trim();
+    if (separator <= 0 || key === '' || Object.hasOwn(fields, key)) {
+      return {status: 'none'};
+    }
+    fields[key] = line.slice(separator + 1).trim();
+  }
+  let end = openingLength + close.index + close[0].length;
+  if (source.startsWith('\r\n', end)) {
+    end += 2;
+  } else if (source[end] === '\n') {
+    end += 1;
+  }
+  return {status: 'match', end, fields: Object.freeze(fields)};
+}
+
+export function createMarkdownFrontmatter<Metadata extends MarkdownPluginData>(
+  options: MarkdownFrontmatterOptions<Metadata>,
+): MarkdownFrontmatter<Metadata> {
+  if (options.name.trim() === '') {
+    throw new TypeError('Markdown frontmatter name must be non-empty');
+  }
+  const name = options.name;
+  const parse = (
+    source: string,
+    isFinal = true,
+  ): MarkdownFrontmatterParseResult<Metadata> => {
+    const parsed = readFrontmatter(source);
+    if (parsed.status === 'defer') {
+      return isFinal ? {status: 'none'} : parsed;
+    }
+    if (parsed.status === 'none') {
+      return parsed;
+    }
+    const metadata = options.parse(parsed.fields);
+    if (!isMarkdownPluginData(metadata)) {
+      throw new TypeError(
+        'Markdown frontmatter metadata must be finite JSON-like data',
+      );
+    }
+    return {
+      status: 'match',
+      contentStart: parsed.end,
+      metadata: freezeMarkdownPluginData(metadata),
+    };
+  };
+  const transform: MarkdownTransform<never> = (document, context) => {
+    const parsed = parse(context.source, context.isFinal);
+    if (parsed.status === 'none') {
+      return document;
+    }
+    if (parsed.status === 'defer') {
+      return {...document, children: []};
+    }
+    const documentData = asDataRecord(document.data);
+    const prior = parseEnvelope(documentData[ENVELOPE_KEY]);
+    const envelope: Envelope = Object.freeze({
+      brand: ENVELOPE_BRAND,
+      version: ENVELOPE_VERSION,
+      values: Object.freeze({
+        ...prior?.values,
+        [name]: parsed.metadata,
+      }),
+    });
+    return {
+      ...document,
+      data: Object.freeze({...documentData, [ENVELOPE_KEY]: envelope}),
+      children: document.children.filter(
+        node => (node.position?.end.offset ?? Infinity) > parsed.contentStart,
+      ),
+    };
+  };
+  const plugin = createMarkdownPlugin({
+    name,
+    apiVersion: 1,
+    transform: markMarkdownTransformTrusted(transform),
+  });
+  return Object.freeze({
+    plugin,
+    parse,
+    getMetadata(document: MarkdownAstRoot<MarkdownExtensionNode>) {
+      const data = asDataRecord(document.data);
+      return parseEnvelope(data[ENVELOPE_KEY])?.values[name] as
+        Metadata | undefined;
+    },
+  });
+}

package/src/Markdown/plugins/index.ts

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @output Public Markdown plugin protocol, factory, and types
+ * @position Subpath entry point: `@astryxdesign/core/Markdown/plugins`
+ */
+
+export {createMarkdownPlugin, isMarkdownExtensionNode} from './protocol';
+export {createMarkdownTextTransform} from './textTransform';
+export type {
+  MarkdownTextTransformContext,
+  MarkdownTextTransformOptions,
+} from './textTransform';
+export {createMarkdownFenceTransform} from './semanticFence';
+export type {
+  MarkdownFenceContext,
+  MarkdownFenceNode,
+  MarkdownFenceTransformOptions,
+} from './semanticFence';
+export {
+  createMarkdownSourceDecoration,
+  getMarkdownSourceDecorations,
+} from './sourceDecoration';
+export type {
+  MarkdownSourceDecoration,
+  MarkdownSourceDecorationOptions,
+  MarkdownSourceDecorationRange,
+} from './sourceDecoration';
+export {createMarkdownFrontmatter} from './frontmatter';
+export type {
+  MarkdownFrontmatter,
+  MarkdownFrontmatterOptions,
+  MarkdownFrontmatterParseResult,
+} from './frontmatter';
+export type {
+  MarkdownPluginData,
+  MarkdownExtensionNode,
+  MarkdownTokenizerInput,
+  MarkdownTokenizeResult,
+  MarkdownSyntaxContribution,
+  MarkdownSyntaxCapability,
+  MarkdownTransformContext,
+  MarkdownTransform,
+  MarkdownExtensionRenderer,
+  MarkdownExtensionRenderers,
+  MarkdownSyntaxPluginDefinition,
+  MarkdownTransformPluginDefinition,
+  MarkdownPluginDefinition,
+  MarkdownPluginEntry,
+  MarkdownNodeOf,
+  MarkdownExtensionsOf,
+} from './protocol';