@texuli/blocks 0.0.0-stage → 0.1.0-next.0

package/dist/text/TextBlockView.svelte

@@ -0,0 +1,177 @@
+<script lang="ts">
+import { checkTextBlock } from './check.js';
+import type { TextBlockViewProps } from './family.js';
+import { resolveTextBlockLabels } from './labels.js';
+import RichText from './RichText.svelte';
+
+/**
+ * The text family renderer: heading, text (paragraphs and rich text), list,
+ * quote and callout. It takes untrusted data and renders only what
+ * `checkTextBlock` accepts; anything else becomes an inert notice.
+ */
+let { block, labels, oninvalid }: TextBlockViewProps = $props();
+
+const check = $derived(checkTextBlock(block));
+const text = $derived(resolveTextBlockLabels(labels));
+
+$effect(() => {
+  if (!check.ok) oninvalid?.(check.issues);
+});
+</script>
+
+{#if !check.ok}
+  <p class="tx-block tx-block-invalid" role="note" data-tx-block="invalid">{text.invalid}</p>
+{:else}
+  {@const b = check.block}
+  {#if b.type === 'heading'}
+    <hgroup class="tx-block tx-heading" data-tx-block="heading" data-tone={b.tone}>
+      {#if b.eyebrow}<p class="tx-heading-eyebrow">{b.eyebrow}</p>{/if}
+      <svelte:element this={`h${b.level}`} class="tx-heading-title" id={b.id}>{b.text}</svelte:element>
+      {#if b.subtitle}<p class="tx-heading-subtitle">{b.subtitle}</p>{/if}
+    </hgroup>
+  {:else if b.type === 'text'}
+    <div class="tx-block tx-text" data-tx-block="text" data-tone={b.tone}>
+      <RichText source={b.markdown} labels={text} />
+    </div>
+  {:else if b.type === 'list'}
+    <svelte:element
+      this={b.ordered ? 'ol' : 'ul'}
+      class="tx-block tx-list"
+      data-tx-block="list"
+      data-tone={b.tone}
+    >
+      {#each b.items as item, i (i)}
+        <li><RichText source={item.text} compact labels={text} /></li>
+      {/each}
+    </svelte:element>
+  {:else if b.type === 'quote'}
+    <figure class="tx-block tx-quote" data-tx-block="quote" data-tone={b.tone}>
+      <blockquote class="tx-quote-body"><RichText source={b.quote} labels={text} /></blockquote>
+      {#if b.cite}<figcaption class="tx-quote-cite"><cite>{b.cite}</cite></figcaption>{/if}
+    </figure>
+  {:else}
+    {@const tone = b.tone ?? 'neutral'}
+    <div class="tx-block tx-callout" role="note" data-tx-block="callout" data-tone={tone}>
+      {#if text.tones[tone] || b.title}
+        <p class="tx-callout-head">
+          {#if text.tones[tone]}<span class="tx-callout-tone">{text.tones[tone]}</span>{/if}
+          {#if b.title}<strong class="tx-callout-title">{b.title}</strong>{/if}
+        </p>
+      {/if}
+      <div class="tx-callout-body"><RichText source={b.body} labels={text} /></div>
+    </div>
+  {/if}
+{/if}
+
+<style>
+  .tx-block {
+    --tx-block-tone: var(--tx-color-border-strong, currentColor);
+    margin: 0;
+    overflow-wrap: anywhere;
+  }
+  /*
+   * Tone colors mark borders and tints only (non-text, 3:1 against both light
+   * and dark surfaces); tone text inherits the page color, so a callout reads
+   * at the host's contrast in any scheme. Tokens override the fallbacks.
+   */
+  [data-tone='accent'] {
+    --tx-block-tone: var(--tx-color-accent, #7c3aed);
+  }
+  [data-tone='info'] {
+    --tx-block-tone: var(--tx-color-info, #2563eb);
+  }
+  [data-tone='success'] {
+    --tx-block-tone: var(--tx-color-success, #16a34a);
+  }
+  [data-tone='warning'] {
+    --tx-block-tone: var(--tx-color-warning, #d97706);
+  }
+  [data-tone='danger'] {
+    --tx-block-tone: var(--tx-color-danger, #dc2626);
+  }
+
+  .tx-heading-eyebrow {
+    margin: 0 0 0.25em;
+    font-size: 0.8125rem;
+    font-weight: 600;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+  }
+  .tx-heading-title {
+    margin: 0;
+    font-weight: 650;
+    line-height: 1.2;
+    text-wrap: balance;
+  }
+  .tx-heading-subtitle {
+    margin: 0.5em 0 0;
+    font-size: 1.125rem;
+  }
+
+  .tx-text {
+    line-height: 1.6;
+  }
+
+  .tx-list {
+    padding-inline-start: 1.5em;
+    line-height: 1.6;
+  }
+  .tx-list > li + li {
+    margin-block-start: 0.375em;
+  }
+
+  .tx-quote {
+    padding-inline-start: 1em;
+    border-inline-start: 3px solid var(--tx-block-tone);
+  }
+  .tx-quote-body {
+    margin: 0;
+    font-size: 1.125em;
+    font-style: italic;
+  }
+  .tx-quote-cite {
+    margin-block-start: 0.5em;
+  }
+  .tx-quote-cite cite {
+    font-style: normal;
+    font-weight: 600;
+  }
+
+  .tx-callout {
+    padding-block: 0.75em;
+    padding-inline: 1em;
+    border: 1px solid color-mix(in srgb, var(--tx-block-tone) 45%, transparent);
+    border-inline-start: 4px solid var(--tx-block-tone);
+    border-radius: 0.5em;
+    background: color-mix(in srgb, var(--tx-block-tone) 8%, transparent);
+  }
+  .tx-callout-head {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5em;
+    align-items: baseline;
+    margin: 0 0 0.375em;
+  }
+  .tx-callout-tone {
+    font-size: 0.8125em;
+    font-weight: 700;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+  }
+
+  .tx-block-invalid {
+    padding: 0.5em 0.75em;
+    border: 1px dashed currentColor;
+    border-radius: 0.375em;
+    font-size: 0.875em;
+  }
+
+  @media (forced-colors: active) {
+    .tx-block {
+      --tx-block-tone: CanvasText;
+    }
+    .tx-callout {
+      border-color: CanvasText;
+    }
+  }
+</style>

package/dist/text/TextBlockView.svelte.d.ts

@@ -0,0 +1,5 @@
+/// <reference path="../css-modules.d.ts" />
+import type { TextBlockViewProps } from './family.js';
+declare const TextBlockView: import("svelte").Component<TextBlockViewProps, {}, "">;
+type TextBlockView = ReturnType<typeof TextBlockView>;
+export default TextBlockView;

package/dist/text/check.d.ts

@@ -0,0 +1,14 @@
+import type { FieldIssue } from '../core/schema/primitives.js';
+import type { TextFamilyBlock } from './engine.js';
+export type TextBlockCheck = {
+    ok: true;
+    block: TextFamilyBlock;
+} | {
+    ok: false;
+    issues: FieldIssue[];
+};
+/**
+ * The only way data reaches a text renderer: untrusted input runs through the
+ * block schemas, then must be one of the text family types.
+ */
+export declare function checkTextBlock(value: unknown): TextBlockCheck;

package/dist/text/check.js

@@ -0,0 +1,13 @@
+import { parseFamilyBlock } from "../core/schema/parse-family.js";
+import { parseTextFamilyBlock } from "../core/schema/text-family.js";
+/**
+ * The only way data reaches a text renderer: untrusted input runs through the
+ * block schemas, then must be one of the text family types.
+ */
+export function checkTextBlock(value) {
+    // Only this family's parser: the renderer does not bundle every family's rules.
+    const parsed = parseFamilyBlock(value, [parseTextFamilyBlock], 'text');
+    if (!parsed.success)
+        return { ok: false, issues: parsed.issues };
+    return { ok: true, block: parsed.data };
+}

package/dist/text/engine.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@texuli/blocks/text/engine` — Svelte-free text family types, guards and labels.
+ * Markdown parser: `@texuli/blocks/text/markdown`. Renderers: `./renderers`.
+ */
+import type { Block, CalloutBlock, FieldIssue, HeadingBlock, ListBlock, QuoteBlock, TextBlock } from '../core/index.js';
+import type { TextBlockLabelOverrides } from './labels.js';
+export { checkTextBlock, type TextBlockCheck } from './check.js';
+export { DEFAULT_TEXT_BLOCK_LABELS, resolveTextBlockLabels, type TextBlockLabelOverrides, type TextBlockLabels, } from './labels.js';
+export declare const TEXT_BLOCK_TYPES: readonly ["heading", "text", "list", "quote", "callout"];
+export type TextFamilyBlockType = (typeof TEXT_BLOCK_TYPES)[number];
+export type TextFamilyBlock = HeadingBlock | TextBlock | ListBlock | QuoteBlock | CalloutBlock;
+export declare function isTextFamilyBlock(block: Block): block is TextFamilyBlock;
+export interface TextBlockViewProps {
+    block: unknown;
+    labels?: TextBlockLabelOverrides;
+    oninvalid?: (issues: FieldIssue[]) => void;
+}

package/dist/text/engine.js

@@ -0,0 +1,10 @@
+/**
+ * `@texuli/blocks/text/engine` — Svelte-free text family types, guards and labels.
+ * Markdown parser: `@texuli/blocks/text/markdown`. Renderers: `./renderers`.
+ */
+export { checkTextBlock } from "./check.js";
+export { DEFAULT_TEXT_BLOCK_LABELS, resolveTextBlockLabels, } from "./labels.js";
+export const TEXT_BLOCK_TYPES = ['heading', 'text', 'list', 'quote', 'callout'];
+export function isTextFamilyBlock(block) {
+    return TEXT_BLOCK_TYPES.includes(block.type);
+}

package/dist/text/family.d.ts

@@ -0,0 +1,7 @@
+import type { Component } from 'svelte';
+import type { TextBlockViewProps } from './engine.js';
+export { isTextFamilyBlock, TEXT_BLOCK_TYPES, type TextBlockViewProps, type TextFamilyBlock, type TextFamilyBlockType, } from './engine.js';
+/** Lazily loads the text family renderer (its own chunk). */
+export declare function loadTextFamily(): Promise<{
+    default: Component<TextBlockViewProps>;
+}>;

package/dist/text/family.js

@@ -0,0 +1,5 @@
+export { isTextFamilyBlock, TEXT_BLOCK_TYPES, } from "./engine.js";
+/** Lazily loads the text family renderer (its own chunk). */
+export function loadTextFamily() {
+    return import('./TextBlockView.svelte');
+}

package/dist/text/index.d.ts

@@ -0,0 +1,12 @@
+/// <reference path="../css-modules.d.ts" />
+/**
+ * `@texuli/blocks` text family (T-blocks-text): heading, text (paragraphs and
+ * rich text), list, quote and callout. No Svelte is imported eagerly:
+ * renderers load through `loadTextFamily()` (its own chunk) or directly from
+ * `@texuli/blocks/text/renderers`. The package root re-exports only the lazy
+ * entry, the guard and the types. The Markdown parser has its own subpath,
+ * `@texuli/blocks/text/markdown`, so neither entry pulls it in eagerly.
+ */
+export { checkTextBlock, type TextBlockCheck } from './check.js';
+export { isTextFamilyBlock, loadTextFamily, TEXT_BLOCK_TYPES, type TextBlockViewProps, type TextFamilyBlock, type TextFamilyBlockType, } from './family.js';
+export { DEFAULT_TEXT_BLOCK_LABELS, resolveTextBlockLabels, type TextBlockLabelOverrides, type TextBlockLabels, } from './labels.js';

package/dist/text/index.js

@@ -0,0 +1,11 @@
+/**
+ * `@texuli/blocks` text family (T-blocks-text): heading, text (paragraphs and
+ * rich text), list, quote and callout. No Svelte is imported eagerly:
+ * renderers load through `loadTextFamily()` (its own chunk) or directly from
+ * `@texuli/blocks/text/renderers`. The package root re-exports only the lazy
+ * entry, the guard and the types. The Markdown parser has its own subpath,
+ * `@texuli/blocks/text/markdown`, so neither entry pulls it in eagerly.
+ */
+export { checkTextBlock } from "./check.js";
+export { isTextFamilyBlock, loadTextFamily, TEXT_BLOCK_TYPES, } from "./family.js";
+export { DEFAULT_TEXT_BLOCK_LABELS, resolveTextBlockLabels, } from "./labels.js";

package/dist/text/labels.d.ts

@@ -0,0 +1,22 @@
+import type { BlockTone } from '../core/index.js';
+/**
+ * Every visible or announced string the text family renders that does not
+ * come from the block itself. Hosts pass translations; English is the default.
+ */
+export interface TextBlockLabels {
+    /** Shown in place of a block that failed validation. */
+    invalid: string;
+    /** Accessible name of a scrollable code fence. */
+    codeBlock: string;
+    /** Accessible state of a checked and an open task item. */
+    taskDone: string;
+    taskOpen: string;
+    /** Visible tone label on callouts (not color alone). Empty hides it. */
+    tones: Record<BlockTone, string>;
+}
+export declare const DEFAULT_TEXT_BLOCK_LABELS: Readonly<TextBlockLabels>;
+/** Merges host overrides over the English defaults (tones merge per key). */
+export declare function resolveTextBlockLabels(overrides?: Partial<Omit<TextBlockLabels, 'tones'>> & {
+    tones?: Partial<Record<BlockTone, string>>;
+}): TextBlockLabels;
+export type TextBlockLabelOverrides = Parameters<typeof resolveTextBlockLabels>[0];

package/dist/text/labels.js

@@ -0,0 +1,29 @@
+export const DEFAULT_TEXT_BLOCK_LABELS = /* @__PURE__ */ Object.freeze({
+    invalid: 'This block could not be shown.',
+    codeBlock: 'Code block',
+    taskDone: 'Done',
+    taskOpen: 'Not done',
+    tones: /* @__PURE__ */ Object.freeze({
+        neutral: '',
+        accent: 'Note',
+        info: 'Info',
+        success: 'Success',
+        warning: 'Warning',
+        danger: 'Important',
+    }),
+});
+/** Merges host overrides over the English defaults (tones merge per key). */
+export function resolveTextBlockLabels(overrides = {}) {
+    const merged = { ...DEFAULT_TEXT_BLOCK_LABELS.tones };
+    for (const [tone, label] of Object.entries(overrides.tones ?? {})) {
+        if (typeof label === 'string' && tone in merged)
+            merged[tone] = label;
+    }
+    return {
+        invalid: overrides.invalid ?? DEFAULT_TEXT_BLOCK_LABELS.invalid,
+        codeBlock: overrides.codeBlock ?? DEFAULT_TEXT_BLOCK_LABELS.codeBlock,
+        taskDone: overrides.taskDone ?? DEFAULT_TEXT_BLOCK_LABELS.taskDone,
+        taskOpen: overrides.taskOpen ?? DEFAULT_TEXT_BLOCK_LABELS.taskOpen,
+        tones: merged,
+    };
+}

package/dist/text/markdown.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Owned, closed Markdown subset for text blocks (T-blocks-text). It turns
+ * already-validated block text into a small tree the Svelte renderers walk.
+ * Nothing here produces HTML: raw tags stay literal text, every link goes
+ * through `safeHref` (untrusted tier), and images render as their alt text
+ * (pictures belong to the media family, which applies `safeImageSrc`).
+ *
+ * Supported: paragraphs, `#` headings, `-`/`*`/`+` and `1.` lists (nested by
+ * indentation, `[ ]`/`[x]` task items), `>` quotes, fenced code, thematic
+ * breaks; inline `**strong**`, `*em*`, `~~del~~`, `` `code` ``, `[text](href)`,
+ * `<https://…>` autolinks, backslash escapes and hard breaks.
+ */
+export type MdInline = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'code';
+    text: string;
+} | {
+    type: 'break';
+} | {
+    type: 'strong' | 'em' | 'del';
+    children: MdInline[];
+} | {
+    type: 'link';
+    href: string | undefined;
+    children: MdInline[];
+};
+export type MdListItem = {
+    checked: boolean | null;
+    children: MdBlock[];
+};
+export type MdBlock = {
+    type: 'paragraph';
+    children: MdInline[];
+} | {
+    type: 'heading';
+    level: 1 | 2 | 3 | 4 | 5 | 6;
+    children: MdInline[];
+} | {
+    type: 'list';
+    ordered: boolean;
+    start: number;
+    items: MdListItem[];
+} | {
+    type: 'quote';
+    children: MdBlock[];
+} | {
+    type: 'code';
+    lang: string | undefined;
+    text: string;
+} | {
+    type: 'rule';
+};
+export interface MdDocument {
+    blocks: MdBlock[];
+}
+/** Nesting and size caps: hostile input degrades to literal text, never recursion blowups. */
+export declare const MARKDOWN_LIMITS: Readonly<{
+    /**
+     * Longest source parsed, equal to the schema's markdown cap. Pathological
+     * inline input stays under ~50 ms at this size.
+     */
+    source: 4000;
+    /** Nested quotes and lists. */
+    blockDepth: 4;
+    /** Nested emphasis and links. */
+    inlineDepth: 6;
+}>;
+/** Parses validated block text into the closed Markdown tree. */
+export declare function parseMarkdown(source: string): MdDocument;
+/** Parses inline Markdown; `depth` caps nested emphasis and links. */
+export declare function parseInline(source: string, depth: number, inLink?: boolean): MdInline[];
+/** Plain text of an inline tree (for accessible names and summaries). */
+export declare function inlineText(nodes: readonly MdInline[]): string;
+/**
+ * Distinct heading levels used anywhere in the tree, ascending. Renderers map
+ * them onto consecutive outline levels (`##` then `####` become h3 then h4).
+ */
+export declare function headingLevels(blocks: readonly MdBlock[]): number[];