@dskripchenko/ui 1.11.0 → 1.12.0

package/README.md

@@ -107,7 +107,7 @@ A short selection — the full catalog is in [Storybook](https://dskripchenko.gi
 
 User docs are translated into four languages — pick yours:
 
-- 🇬🇧 **English** (default): [getting-started](./docs/en/getting-started.md), [theming](./docs/en/theming.md), [tokens](./docs/en/tokens.md), [icons](./docs/en/icons.md), [patterns](./docs/en/patterns.md), [validation](./docs/en/validation.md), [charts](./docs/en/charts.md), [i18n](./docs/en/i18n.md)
+- 🇬🇧 **English** (default): [getting-started](./docs/en/getting-started.md), [theming](./docs/en/theming.md), [tokens](./docs/en/tokens.md), [icons](./docs/en/icons.md), [patterns](./docs/en/patterns.md), [validation](./docs/en/validation.md), [charts](./docs/en/charts.md), [markdown](./docs/en/markdown.md), [i18n](./docs/en/i18n.md)
 - 🇷🇺 **Русский**: [docs/ru/](./docs/ru/)
 - 🇩🇪 **Deutsch**: [docs/de/](./docs/de/)
 - 🇨🇳 **中文**: [docs/zh/](./docs/zh/)

package/dist/components/Markdown/UidMarkdown.vue.d.ts

@@ -0,0 +1,43 @@
+import { UidMarkdownCalloutKind } from './markdown.js';
+import { UidMarkdownBlockRenderer } from './blockRenderers.js';
+export interface UidMarkdownProps {
+    /** The markdown text. */
+    source?: string;
+    /** Shows a table of contents built from the headings. */
+    toc?: boolean;
+    /** Deepest heading level in the table of contents, 2 to 6. */
+    tocDepth?: number;
+    /** Title of the table of contents; the locale's by default. */
+    tocLabel?: string;
+    /** The base relative links resolve against. */
+    linkBase?: string;
+    /** Drops a trailing `.md` from relative links; on by default when `linkBase` is set. */
+    stripMdExtension?: boolean;
+    /** The base relative image paths resolve against. */
+    imageBase?: string;
+    /**
+     * Opens relative and anchor links in the same tab (the default). Off, every
+     * link but an anchor opens in a new tab — for a preview next to a form,
+     * where leaving the page would lose the input.
+     */
+    internalLinksInPlace?: boolean;
+    /** Callout titles; override the locale's, kind by kind. */
+    calloutTitles?: Partial<Record<UidMarkdownCalloutKind, string>>;
+    /** Renderers for fenced blocks by language; override the provided ones. */
+    blockRenderers?: Record<string, UidMarkdownBlockRenderer>;
+}
+declare const _default: import('vue').DefineComponent<UidMarkdownProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<UidMarkdownProps> & Readonly<{}>, {
+    source: string;
+    toc: boolean;
+    tocDepth: number;
+    tocLabel: string;
+    linkBase: string;
+    stripMdExtension: boolean;
+    imageBase: string;
+    internalLinksInPlace: boolean;
+    calloutTitles: Partial<Record<UidMarkdownCalloutKind, string>>;
+    blockRenderers: Record<string, UidMarkdownBlockRenderer>;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    root: HTMLDivElement;
+}, HTMLDivElement>;
+export default _default;

package/dist/components/Markdown/blockRenderers.d.ts

@@ -0,0 +1,36 @@
+import { InjectionKey } from 'vue';
+/** What a block renderer returns for one fenced code block. */
+export interface UidMarkdownBlockResult {
+    /**
+     * Markup to insert in place of the code block.
+     *
+     * Inserted as is (`v-html`): the renderer is responsible for its safety.
+     * Return only markup you built yourself with every piece of user text
+     * escaped — for example SVG from @dskripchenko/diagrams, which escapes
+     * labels by construction. Never return the block's source unescaped.
+     */
+    html?: string;
+    /** Why the block could not be rendered; the block is then shown as code with this message. */
+    error?: string;
+}
+/**
+ * Renders a fenced code block of one language (```mermaid, ```chart, …)
+ * instead of showing it as code. May be asynchronous — the block shows a
+ * placeholder until it settles. A thrown error or a rejected promise is
+ * treated like `{ error }`.
+ */
+export type UidMarkdownBlockRenderer = (code: string, ctx: {
+    language: string;
+    index: number;
+}) => UidMarkdownBlockResult | Promise<UidMarkdownBlockResult>;
+/** Block renderers by fence language (lower case). */
+export type UidMarkdownBlockRenderers = Readonly<Record<string, UidMarkdownBlockRenderer>>;
+export declare const markdownBlockRenderersKey: InjectionKey<UidMarkdownBlockRenderers>;
+/**
+ * Registers block renderers for every UidMarkdown below the calling
+ * component — call it in the root component's setup once. Application-wide:
+ * `app.provide(markdownBlockRenderersKey, renderers)`. Renderers passed to
+ * UidMarkdown through its prop take precedence, language by language.
+ */
+export declare function provideMarkdownBlockRenderers(renderers: UidMarkdownBlockRenderers): void;
+export declare function useMarkdownBlockRenderers(): UidMarkdownBlockRenderers;

package/dist/components/Markdown/index.d.ts

@@ -0,0 +1,6 @@
+export { default as UidMarkdown } from './UidMarkdown.vue';
+export type { UidMarkdownProps } from './UidMarkdown.vue';
+export { createSlugger, escapeHtml, renderMarkdown, resolveAgainst, splitMarkdown, } from './markdown.js';
+export type { MarkdownHeading, MarkdownOptions, MarkdownSegment, Slugger, UidMarkdownCalloutKind, } from './markdown.js';
+export { markdownBlockRenderersKey, provideMarkdownBlockRenderers, useMarkdownBlockRenderers, } from './blockRenderers.js';
+export type { UidMarkdownBlockRenderer, UidMarkdownBlockRenderers, UidMarkdownBlockResult, } from './blockRenderers.js';

package/dist/components/Markdown/markdown.d.ts

@@ -0,0 +1,71 @@
+/**
+ * A small, dependency-free markdown → HTML renderer.
+ *
+ * It covers the everyday subset — headings, paragraphs, emphasis, inline code,
+ * fenced code, links, images, block quotes and callouts, lists, tables and
+ * rules — which is what a description, a note or a documentation page in an
+ * admin usually holds. A host that needs the full CommonMark grammar registers
+ * its own `markdown` field, entry or layout.
+ *
+ * Safety: the source is HTML-escaped BEFORE any markup is produced, so raw
+ * HTML in the markdown is shown as text, never executed; link and image URLs
+ * are limited to http(s), mailto, relative and anchor targets.
+ *
+ * Ported from laravel-admin core, where it was born; the kit is now its home.
+ */
+export declare function escapeHtml(text: string): string;
+/** A heading met while rendering, for a table of contents. */
+export interface MarkdownHeading {
+    level: number;
+    /** The heading's plain text. */
+    text: string;
+    id: string;
+}
+/** Turns heading text into a unique anchor id; shared across the chunks of one document. */
+export type Slugger = (text: string) => string;
+export declare function createSlugger(): Slugger;
+export interface MarkdownOptions {
+    /** Gives the headings anchor ids. */
+    slugger?: Slugger | null;
+    /** Called for every heading, in document order. */
+    onHeading?: (heading: MarkdownHeading) => void;
+    /**
+     * The base relative links resolve against, the way a browser resolves them
+     * against `<base href>`. Absolute, anchor and scheme links are left alone.
+     */
+    linkBase?: string | null;
+    /** Drops a trailing `.md` from relative links resolved through linkBase. */
+    stripMdExtension?: boolean;
+    /** The base relative image paths resolve against. */
+    imageBase?: string | null;
+    /**
+     * Opens relative and anchor links in place. By default every link opens in
+     * a new tab, which suits a note in a form; a documentation page wants its
+     * own links to navigate.
+     */
+    internalLinksInPlace?: boolean;
+    /** Titles of `[!NOTE]`-style callouts; English when not given. */
+    calloutTitles?: Partial<Record<UidMarkdownCalloutKind, string>>;
+}
+export type UidMarkdownCalloutKind = 'note' | 'tip' | 'important' | 'warning' | 'caution';
+/**
+ * Resolves an escaped relative URL against a base. The result is escaped
+ * again; an absolute base keeps its origin, a path base yields a path.
+ */
+export declare function resolveAgainst(escapedUrl: string, base: string, stripMd?: boolean): string;
+export declare function renderMarkdown(source: string | null | undefined, opts?: MarkdownOptions): string;
+/** A piece of a markdown document: text to render, or a top-level fenced code block. */
+export type MarkdownSegment = {
+    kind: 'text';
+    source: string;
+} | {
+    kind: 'code';
+    code: string;
+    language: string;
+};
+/**
+ * Splits a document at its top-level fenced code blocks, so that a caller can
+ * draw the code with a real highlighter and the rest with renderMarkdown.
+ * Fences inside block quotes stay in the text.
+ */
+export declare function splitMarkdown(source: string | null | undefined): MarkdownSegment[];