@djangocfg/ui-tools 2.1.290 → 2.1.292

package/src/tools/MarkdownEditor/mentionPresets.ts

@@ -0,0 +1,49 @@
+import type { MentionMarkdownRenderer } from './types';
+
+/**
+ * Escape characters that have meaning in markdown link/inline contexts.
+ * Conservative — covers the chars that would break `[text](url)` and
+ * inline emphasis when a label contains them.
+ */
+const escapeMd = (s: string): string => s.replace(/([\\\[\]()_*~`])/g, '\\$1');
+
+/**
+ * Built-in serializers for the `MentionConfig.renderMarkdown` callback.
+ *
+ * Pick one based on what consumes the markdown:
+ *
+ * - LLM / chat composer    → `plainAt`     (the default)
+ * - Plain text export      → `plainLabel`
+ * - Web app with deep-link → `markdownLink(baseUrl)`
+ * - Notion / Linear-style  → `customUri(scheme, kind)`
+ * - Slack-style id refs    → `slackStyle`
+ * - HTML-allowing renderer → `htmlSpan(className?)`
+ *
+ * Or pass a custom function — the type is just `(attrs) => string`.
+ */
+export const mentionPresets = {
+  /** "@Label" — default, ideal for chat where LLMs read the text. */
+  plainAt: (({ label, id }) => `@${label || id}`) as MentionMarkdownRenderer,
+
+  /** "Label" — bare label, no @ prefix. */
+  plainLabel: (({ label, id }) => label || id) as MentionMarkdownRenderer,
+
+  /** "[@Label](baseUrl/id)" — clickable markdown link. */
+  markdownLink: (baseUrl: string): MentionMarkdownRenderer =>
+    ({ label, id }) =>
+      `[@${escapeMd(label || id)}](${baseUrl}${encodeURIComponent(id)})`,
+
+  /** "@[Label](scheme://kind/id)" — Notion / Linear-style custom URI. */
+  customUri: (scheme: string, kind: string): MentionMarkdownRenderer =>
+    ({ label, id }) =>
+      `@[${escapeMd(label || id)}](${scheme}://${kind}/${encodeURIComponent(id)})`,
+
+  /** "<@id>" — Slack-style id-only reference (label dropped — receivers resolve it). */
+  slackStyle: (({ id }) => `<@${id}>`) as MentionMarkdownRenderer,
+
+  /** Inline HTML span — for products that consume markdown with raw HTML allowed. */
+  htmlSpan:
+    (className = 'mention'): MentionMarkdownRenderer =>
+    ({ label, id }) =>
+      `<span class="${className}" data-mention-id="${encodeURIComponent(id)}">@${escapeMd(label || id)}</span>`,
+};

package/src/tools/MarkdownEditor/types.ts

@@ -1,5 +1,3 @@
-import type { ReactNode } from 'react';
-
 /** Item that can be mentioned via @ trigger */
 export interface MentionItem {
   id: string;
@@ -8,6 +6,27 @@ export interface MentionItem {
   thumbnail?: string;
 }
 
+/**
+ * Attributes available when rendering a mention to markdown.
+ *
+ * Same shape Tiptap stores on the `mention` node — `id` is the stable
+ * identifier the suggestion popover injected, `label` is the human text
+ * shown to the user. Either field may be empty if the upstream config
+ * never populated it; renderers should fall back accordingly.
+ */
+export interface MentionAttrs {
+  id: string;
+  label: string;
+}
+
+/**
+ * Function that converts a mention node into its markdown serialization.
+ *
+ * The returned string is what `@tiptap/markdown` writes into the markdown
+ * output of `MarkdownEditor.getMarkdown()`.
+ */
+export type MentionMarkdownRenderer = (attrs: MentionAttrs) => string;
+
 /** Mention configuration */
 export interface MentionConfig {
   /** Trigger character (default: '@') */
@@ -16,4 +35,16 @@ export interface MentionConfig {
   items: MentionItem[];
   /** Max dropdown items (default: 5) */
   maxItems?: number;
+  /**
+   * Custom serializer for mentions when `MarkdownEditor.getMarkdown()` runs.
+   *
+   * Defaults to `mentionPresets.plainAt` which yields `@<label>` (or `@<id>`
+   * when `label` is missing). Use one of `mentionPresets`, or supply your
+   * own function for full control over how mentions appear in the output
+   * markdown string.
+   *
+   * Note: this only affects the *markdown* output. `editor.getText()` and
+   * the rendered DOM still go through `renderText` (`@<label>` by default).
+   */
+  renderMarkdown?: MentionMarkdownRenderer;
 }

package/src/tools/OpenapiViewer/README.md

@@ -251,7 +251,8 @@ interface PlaygroundConfig {
    *  the longread as top-level sections. */
   schemaGrouping?: 'selector' | 'sections';
   /** Sync the active endpoint anchor to ``window.location.hash`` as
-   *  the user scrolls (sections mode). Default: off. */
+   *  the user scrolls (sections mode). Default: on. Pass ``false`` to
+   *  opt out if the host page manages the hash itself. */
   urlSync?: boolean;
 }
 

package/src/tools/OpenapiViewer/components/DocsLayout/index.tsx

@@ -31,7 +31,11 @@ export const DocsLayout: React.FC = () => {
     const grouping = config.schemaGrouping ?? 'selector';
     const preloadAll = grouping === 'sections';
     const urlSyncEnabled =
-        typeof config.urlSync === 'boolean' ? config.urlSync : Boolean(config.urlSync?.enabled);
+        config.urlSync === undefined
+            ? true
+            : typeof config.urlSync === 'boolean'
+                ? config.urlSync
+                : Boolean(config.urlSync.enabled);
 
     const {
         endpoints,

package/src/tools/OpenapiViewer/types.ts

@@ -114,11 +114,11 @@ export interface PlaygroundConfig {
    *    rendered back-to-back in the docs column. Scrollspy picks the
    *    active schema based on what's visible. */
   schemaGrouping?: 'selector' | 'sections';
-  /** Optional URL-hash sync. When enabled, the viewer reads/writes
-   *  ``#<schemaId>/<anchor>`` on the browser location. Falsy value (the
-   *  default) keeps the viewer hash-free. Set to an object with
-   *  ``{ enabled: true }`` to opt in; future fields (e.g. a custom
-   *  adapter) stay backwards compatible. */
+  /** URL-hash sync. When enabled, the viewer reads/writes
+   *  ``#<schemaId>/<anchor>`` on the browser location so deep-links
+   *  to a specific endpoint work out of the box. Defaults to ``true`` —
+   *  pass ``false`` (or ``{ enabled: false }``) to opt out if the host
+   *  page already manages the hash itself. */
   urlSync?: boolean | { enabled: boolean };
 }
 

package/src/tools/index.ts

@@ -223,8 +223,14 @@ export type {
 } from './CodeEditor/types';
 
 // Export MarkdownEditor (Tiptap ~200KB)
-export { MarkdownEditor } from './MarkdownEditor';
-export type { MarkdownEditorProps, MentionItem, MentionConfig } from './MarkdownEditor';
+export { MarkdownEditor, mentionPresets } from './MarkdownEditor';
+export type {
+  MarkdownEditorProps,
+  MentionItem,
+  MentionConfig,
+  MentionAttrs,
+  MentionMarkdownRenderer,
+} from './MarkdownEditor';
 
 // Export Media Cache Store
 export {