@djangocfg/ui-tools 2.1.289 → 2.1.291

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.289",
+  "version": "2.1.291",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -74,7 +74,8 @@
       "import": "./src/tools/CodeEditor/index.ts",
       "require": "./src/tools/CodeEditor/index.ts"
     },
-    "./styles": "./src/styles/index.css"
+    "./styles": "./src/styles/index.css",
+    "./dist.css": "./dist/index.css"
   },
   "files": [
     "dist",
@@ -90,8 +91,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.289",
-    "@djangocfg/ui-core": "^2.1.289",
+    "@djangocfg/i18n": "^2.1.291",
+    "@djangocfg/ui-core": "^2.1.291",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -101,30 +102,34 @@
     "zustand": "^5.0.0"
   },
   "dependencies": {
-    "@tiptap/core": "^3.20.1",
-    "@tiptap/react": "^3.20.1",
-    "@tiptap/starter-kit": "^3.20.1",
-    "@tiptap/extension-placeholder": "^3.20.1",
-    "@tiptap/extension-mention": "^3.20.1",
-    "@tiptap/suggestion": "^3.20.1",
-    "@tiptap/markdown": "^3.20.1",
-    "@tiptap/pm": "^3.20.1",
     "@rjsf/core": "^6.1.2",
     "@rjsf/utils": "^6.1.2",
     "@rjsf/validator-ajv8": "^6.1.2",
     "@rpldy/uploady": "^1.8.5",
+    "@tiptap/core": "^3.20.1",
+    "@tiptap/extension-mention": "^3.20.1",
+    "@tiptap/extension-placeholder": "^3.20.1",
+    "@tiptap/markdown": "^3.20.1",
+    "@tiptap/pm": "^3.20.1",
+    "@tiptap/react": "^3.20.1",
+    "@tiptap/starter-kit": "^3.20.1",
+    "@tiptap/suggestion": "^3.20.1",
     "@vidstack/react": "next",
     "@wavesurfer/react": "^1.0.12",
     "maplibre-gl": "^4.7.1",
     "media-icons": "next",
     "mermaid": "^11.12.0",
     "monaco-editor": "^0.55.1",
+    "openapi-sampler": "^1.7.2",
     "prism-react-renderer": "^2.4.1",
+    "prismjs": "^1.30.0",
     "react-json-tree": "^0.20.0",
     "react-lottie-player": "^2.1.0",
     "react-map-gl": "^8.1.0",
     "react-markdown": "10.1.0",
     "react-zoom-pan-pinch": "^3.7.0",
+    "rehype-raw": "^7.0.0",
+    "rehype-sanitize": "^6.0.0",
     "remark-gfm": "4.0.1",
     "vidstack": "next",
     "wavesurfer.js": "^7.12.1"
@@ -134,10 +139,10 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.289",
+    "@djangocfg/i18n": "^2.1.291",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.289",
-    "@djangocfg/ui-core": "^2.1.289",
+    "@djangocfg/typescript-config": "^2.1.291",
+    "@djangocfg/ui-core": "^2.1.291",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",

package/src/components/markdown/MarkdownMessage.tsx

@@ -2,8 +2,37 @@
 
 import React from 'react';
 import ReactMarkdown from 'react-markdown';
+import rehypeRaw from 'rehype-raw';
+import rehypeSanitize, { defaultSchema } from 'rehype-sanitize';
 import remarkGfm from 'remark-gfm';
 
+// Allow-list HTML that OpenAPI descriptions commonly use — we want
+// ``<b>``/``<code>``/``<br>`` to render, not to appear as literal text.
+// Built on top of ``rehype-sanitize``'s default schema so we keep the
+// XSS protection (no ``<script>``, no ``on*`` handlers, no ``javascript:``
+// URLs); we just extend the tag allow-list with safe presentational
+// elements that are in wide use in API docs.
+const HTML_SCHEMA = {
+  ...defaultSchema,
+  tagNames: [
+    ...(defaultSchema.tagNames ?? []),
+    'br',
+    'b',
+    'i',
+    'u',
+    's',
+    'sub',
+    'sup',
+    'small',
+    'mark',
+    'kbd',
+    'code',
+    'pre',
+    'details',
+    'summary',
+  ],
+};
+
 import { CopyButton } from '@djangocfg/ui-core/components';
 import { useResolvedTheme } from '@djangocfg/ui-core/hooks';
 
@@ -331,6 +360,16 @@ const hasMarkdownSyntax = (text: string): boolean => {
     return true;
   }
 
+  // Inline HTML tags (``<br>``, ``<b>``, ``<code>``, …) — used widely
+  // in OpenAPI descriptions. Without this branch the plain-text fast
+  // path would escape them and the user sees literal angle brackets.
+  // The regex matches opening, closing, and self-closing tags without
+  // being too clever about malformed HTML; it's an affordance test,
+  // not a validator.
+  if (/<\/?[a-zA-Z][a-zA-Z0-9-]*(\s[^>]*)?\/?>/.test(text)) {
+    return true;
+  }
+
   // Common markdown patterns
   const markdownPatterns = [
     /^#{1,6}\s/m,           // Headers
@@ -549,6 +588,13 @@ export const MarkdownMessage: React.FC<MarkdownMessageProps> = ({
       >
         <ReactMarkdown
           remarkPlugins={[remarkGfm]}
+          // ``rehype-raw`` parses inline HTML in the source (OpenAPI
+          // ``description`` fields often contain ``<br>`` / ``<b>`` /
+          // ``<code>``). ``rehype-sanitize`` with our extended schema
+          // runs after it so the allowed tags pass through while
+          // anything risky (scripts, event handlers, javascript: urls)
+          // is stripped.
+          rehypePlugins={[rehypeRaw, [rehypeSanitize, HTML_SCHEMA]]}
           components={components}
         >
           {displayContent}

package/src/tools/MarkdownEditor/MarkdownEditor.tsx

@@ -47,7 +47,23 @@ export interface MarkdownEditorProps {
   className?: string;
   disabled?: boolean;
   showToolbar?: boolean;
-  /** @mention autocomplete config */
+  /**
+   * `@`-mention autocomplete config.
+   *
+   * IMPORTANT: Tiptap's `useEditor` initialises the editor exactly once.
+   * The `Mention` extension is only registered when `mentions` is truthy
+   * on the FIRST render — handing in a real config later (e.g. after an
+   * async items fetch) silently does nothing, and typing `@` will not
+   * open the popover.
+   *
+   * If you want mentions even with async-loaded items, pass
+   * `{ items: [] }` from the very first render and update the array
+   * when data arrives. Either keep the `MentionConfig` object identity
+   * stable across renders and mutate `items` in place (the suggestion
+   * plugin captures the config by closure and reads `items` on each
+   * query), or accept that swapping the whole object reference is a
+   * no-op for the live editor.
+   */
   mentions?: MentionConfig;
   /** Called when mentioned IDs change */
   onMentionIdsChange?: (ids: string[]) => void;
@@ -68,6 +84,31 @@ export function MarkdownEditor({
 }: MarkdownEditorProps) {
   const isExternalUpdate = useRef(false);
 
+  // ── Dev-mode trap detector ──
+  // Tiptap initialises the editor once with the extensions array from
+  // first render. If `mentions` is undefined on mount and becomes
+  // truthy later, the Mention extension is never installed and the
+  // user-visible @-trigger silently does nothing. Catch this early so
+  // future consumers don't spend hours debugging why @ does nothing.
+  const initialMentionsDefinedRef = useRef<boolean>(mentions !== undefined);
+  const warnedRef = useRef(false);
+  if (
+    process.env.NODE_ENV !== 'production' &&
+    !initialMentionsDefinedRef.current &&
+    mentions !== undefined &&
+    !warnedRef.current
+  ) {
+    warnedRef.current = true;
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[MarkdownEditor] `mentions` flipped from undefined to a config ' +
+        'after mount. Tiptap only installs the Mention extension on first ' +
+        'render — the @-popover will NOT work for this editor instance. ' +
+        'Pass `{ items: [] }` from the very first render and mutate `.items` ' +
+        'in place instead.',
+    );
+  }
+
   const extensions = useMemo(() => {
     const exts: AnyExtension[] = [
       StarterKit.configure({ heading: { levels: [1, 2, 3] } }),

package/src/tools/OpenapiViewer/OpenapiViewer.story.tsx

@@ -1,4 +1,4 @@
-import { defineStory, useSelect, useValue } from '@djangocfg/playground';
+import { defineStory, useSelect, useValue, useBoolean } from '@djangocfg/playground';
 import { Playground } from './index';
 import { LazyOpenapiViewer } from './lazy';
 import type { PlaygroundConfig } from './types';
@@ -11,13 +11,18 @@ export default defineStory({
 });
 
 // ============================================================================
-// Schema configs
+// Schema fixtures
 // ============================================================================
 
+// Petstore's own ``servers[0].url`` is just ``/api/v3`` (relative),
+// which makes code samples look like they target ``localhost`` when
+// viewed from the playground. Override with the canonical public host
+// so the generated curl/fetch/etc snippets are runnable as-is.
 const PETSTORE_SCHEMA = {
   id: 'petstore',
   name: 'Petstore API',
   url: 'https://petstore3.swagger.io/api/v3/openapi.json',
+  baseUrl: 'https://petstore3.swagger.io/api/v3',
 } as const;
 
 const HTTPBIN_SCHEMA = {
@@ -28,15 +33,18 @@ const HTTPBIN_SCHEMA = {
 
 const MULTI_SCHEMAS = [PETSTORE_SCHEMA, HTTPBIN_SCHEMA] as const;
 
-// Simulates a real multi-group setup (like cmdop with 5+ API groups)
+// Simulates a real multi-group setup (like cmdop with 5+ API groups).
+// All clones share the canonical Petstore host so code samples
+// render with a real runnable URL.
+const PETSTORE_BASE = 'https://petstore3.swagger.io/api/v3';
 const MANY_SCHEMAS = [
   PETSTORE_SCHEMA,
   HTTPBIN_SCHEMA,
-  { id: 'machines', name: 'Machines API', url: 'https://petstore3.swagger.io/api/v3/openapi.json' },
-  { id: 'terminal', name: 'Terminal API', url: 'https://petstore3.swagger.io/api/v3/openapi.json' },
-  { id: 'skills', name: 'Skills API', url: 'https://petstore3.swagger.io/api/v3/openapi.json' },
-  { id: 'system', name: 'System API', url: 'https://petstore3.swagger.io/api/v3/openapi.json' },
-  { id: 'site', name: 'Site API', url: 'https://petstore3.swagger.io/api/v3/openapi.json' },
+  { id: 'machines', name: 'Machines API', url: 'https://petstore3.swagger.io/api/v3/openapi.json', baseUrl: PETSTORE_BASE },
+  { id: 'terminal', name: 'Terminal API', url: 'https://petstore3.swagger.io/api/v3/openapi.json', baseUrl: PETSTORE_BASE },
+  { id: 'skills', name: 'Skills API', url: 'https://petstore3.swagger.io/api/v3/openapi.json', baseUrl: PETSTORE_BASE },
+  { id: 'system', name: 'System API', url: 'https://petstore3.swagger.io/api/v3/openapi.json', baseUrl: PETSTORE_BASE },
+  { id: 'site', name: 'Site API', url: 'https://petstore3.swagger.io/api/v3/openapi.json', baseUrl: PETSTORE_BASE },
 ] as const;
 
 // ============================================================================
@@ -44,60 +52,34 @@ const MANY_SCHEMAS = [
 // ============================================================================
 
 /**
- * Interactive — default schema is adjustable.
+ * Default — single-schema mode with the most common configuration knobs
+ * exposed as toggles. Replaces the earlier Interactive / SingleSchema /
+ * WithBaseUrl / NoDefault / CustomUrl stories, which were all "this
+ * component with different props" variations.
  */
-export const Interactive = () => {
-  const [defaultSchema] = useSelect('defaultSchema', {
-    options: ['petstore', 'httpbin'] as const,
-    defaultValue: 'petstore',
-    label: 'Default Schema',
-    description: 'Which schema to load first',
+export const Default = () => {
+  const [schemaUrl] = useValue('schemaUrl', {
+    defaultValue: PETSTORE_SCHEMA.url,
+    label: 'Schema URL',
+    description: 'Any OpenAPI 3.x JSON endpoint',
   });
 
-  const config: PlaygroundConfig = {
-    schemas: [...MULTI_SCHEMAS],
-    defaultSchemaId: defaultSchema,
-  };
-
-  return (
-    <div className="min-h-[600px]">
-      <Playground config={config} />
-    </div>
-  );
-};
-
-/**
- * With baseUrl override — forces a specific request host, ignoring
- * `schema.servers[0].url`. Useful when docs are hosted on a different
- * origin than the API, or when the schema has no servers entry.
- */
-export const WithBaseUrl = () => {
   const [baseUrl] = useValue('baseUrl', {
-    defaultValue: 'https://petstore3.swagger.io/api/v3',
-    label: 'Base URL',
-    description: 'Overrides schema.servers[0].url for every request',
+    defaultValue: '',
+    label: 'Base URL override',
+    description: 'Empty = use servers[0].url from the schema',
   });
 
-  const config: PlaygroundConfig = {
-    schemas: [PETSTORE_SCHEMA],
-    defaultSchemaId: 'petstore',
-    baseUrl,
-  };
-
-  return (
-    <div className="min-h-[600px]">
-      <Playground config={config} />
-    </div>
-  );
-};
+  const [autoSelect] = useBoolean('autoSelectDefault', {
+    defaultValue: true,
+    label: 'Auto-select default schema',
+    description: 'When off, tests the "no defaultSchemaId" code path',
+  });
 
-/**
- * Single schema — no Combobox switcher shown (schemas.length === 1).
- */
-export const SingleSchema = () => {
   const config: PlaygroundConfig = {
-    schemas: [PETSTORE_SCHEMA],
-    defaultSchemaId: 'petstore',
+    schemas: [{ id: 'custom', name: 'Schema', url: schemaUrl }],
+    defaultSchemaId: autoSelect ? 'custom' : undefined,
+    baseUrl: baseUrl || undefined,
   };
 
   return (
@@ -108,12 +90,20 @@ export const SingleSchema = () => {
 };
 
 /**
- * Multiple schemas with Combobox switcher.
- * Switch between Petstore and HTTPBin to see different endpoint sets.
+ * MultiSchema — multiple schemas with the Combobox switcher. Count
+ * is adjustable to exercise both the short-list layout and the
+ * long-list behaviour (cmdop-style setups with 7+ APIs).
  */
-export const MultipleSchemas = () => {
+export const MultiSchema = () => {
+  const [count] = useSelect('count', {
+    options: ['2', '7'] as const,
+    defaultValue: '2',
+    label: 'Schema count',
+    description: '2 uses Petstore+HTTPBin; 7 stress-tests the Combobox',
+  });
+
   const config: PlaygroundConfig = {
-    schemas: [...MULTI_SCHEMAS],
+    schemas: count === '2' ? [...MULTI_SCHEMAS] : [...MANY_SCHEMAS],
     defaultSchemaId: 'petstore',
   };
 
@@ -125,14 +115,14 @@ export const MultipleSchemas = () => {
 };
 
 /**
- * Sections grouping — all schemas rendered as top-level headings in the
- * sidebar, with every endpoint laid out on the same page. URL hash sync
- * is enabled so scrolling updates ``#<schemaId>/<anchor>``.
+ * SectionsGrouping — alternate layout: every schema's endpoints get
+ * rendered on the same page as top-level sections, with a sidebar
+ * that stacks them. URL hash sync writes ``#<schemaId>/<anchor>``
+ * as the user scrolls so deep-linking keeps working.
  */
 export const SectionsGrouping = () => {
-  const [urlSync] = useSelect('urlSync', {
-    options: ['on', 'off'] as const,
-    defaultValue: 'on',
+  const [urlSync] = useBoolean('urlSync', {
+    defaultValue: true,
     label: 'URL hash sync',
     description: 'Writes #<schemaId>/<anchor> as you scroll',
   });
@@ -141,7 +131,7 @@ export const SectionsGrouping = () => {
     schemas: [...MULTI_SCHEMAS],
     defaultSchemaId: 'petstore',
     schemaGrouping: 'sections',
-    urlSync: urlSync === 'on',
+    urlSync,
   };
 
   return (
@@ -152,91 +142,37 @@ export const SectionsGrouping = () => {
 };
 
 /**
- * Many schemas (7+) — tests Combobox with a long list.
- * Simulates a real setup like cmdop with machines, terminal, skills, etc.
+ * Errors — consolidated failure paths. Pick a scenario via the toggle:
+ *   - ``broken``: single schema that 404s → full-panel error state.
+ *   - ``mixed``: valid + broken side-by-side → tests switching between.
+ *   - ``empty``: no schemas configured at all → empty-state UI.
  */
-export const ManySchemas = () => {
-  const config: PlaygroundConfig = {
-    schemas: [...MANY_SCHEMAS],
-    defaultSchemaId: 'petstore',
-  };
-
-  return (
-    <div className="min-h-[600px]">
-      <Playground config={config} />
-    </div>
-  );
-};
-
-/**
- * No defaultSchemaId — should auto-select the first schema.
- */
-export const NoDefault = () => {
-  const config: PlaygroundConfig = {
-    schemas: [...MULTI_SCHEMAS],
-  };
-
-  return (
-    <div className="min-h-[600px]">
-      <Playground config={config} />
-    </div>
-  );
-};
-
-/**
- * Error state — invalid schema URL that will fail to fetch.
- * Tests error handling and UI feedback.
- */
-export const ErrorState = () => {
-  const config: PlaygroundConfig = {
-    schemas: [
-      {
-        id: 'broken',
-        name: 'Broken API',
-        url: 'https://httpbin.org/status/404',
-      },
-    ],
-    defaultSchemaId: 'broken',
-  };
-
-  return (
-    <div className="min-h-[600px]">
-      <Playground config={config} />
-    </div>
-  );
-};
-
-/**
- * Mixed valid + broken — one schema works, one fails.
- * Tests switching between working and broken schemas.
- */
-export const MixedValidBroken = () => {
-  const config: PlaygroundConfig = {
-    schemas: [
-      PETSTORE_SCHEMA,
-      {
-        id: 'broken',
-        name: 'Broken API (404)',
-        url: 'https://httpbin.org/status/404',
-      },
-    ],
-    defaultSchemaId: 'petstore',
-  };
-
-  return (
-    <div className="min-h-[600px]">
-      <Playground config={config} />
-    </div>
-  );
-};
+export const Errors = () => {
+  const [scenario] = useSelect('scenario', {
+    options: ['broken', 'mixed', 'empty'] as const,
+    defaultValue: 'broken',
+    label: 'Failure scenario',
+  });
 
-/**
- * Empty schemas array — edge case, no schemas provided.
- */
-export const EmptySchemas = () => {
-  const config: PlaygroundConfig = {
-    schemas: [],
-  };
+  const config: PlaygroundConfig = (() => {
+    switch (scenario) {
+      case 'broken':
+        return {
+          schemas: [{ id: 'broken', name: 'Broken API', url: 'https://httpbin.org/status/404' }],
+          defaultSchemaId: 'broken',
+        };
+      case 'mixed':
+        return {
+          schemas: [
+            PETSTORE_SCHEMA,
+            { id: 'broken', name: 'Broken API (404)', url: 'https://httpbin.org/status/404' },
+          ],
+          defaultSchemaId: 'petstore',
+        };
+      case 'empty':
+        return { schemas: [] };
+    }
+  })();
 
   return (
     <div className="min-h-[600px]">
@@ -246,8 +182,9 @@ export const EmptySchemas = () => {
 };
 
 /**
- * LazyOpenapiViewer — the production lazy-loaded variant.
- * Shows loading spinner while ~400KB of OpenAPI components load.
+ * Lazy — production lazy-loaded variant. Shows the loading spinner
+ * while the ~400 KB OpenAPI viewer chunk is fetched. Only path you
+ * should use in an actual app bundle.
  */
 export const Lazy = () => {
   const config: PlaygroundConfig = {
@@ -261,31 +198,3 @@ export const Lazy = () => {
     </div>
   );
 };
-
-/**
- * Custom schema URL — paste any OpenAPI 3.x schema URL to test.
- */
-export const CustomUrl = () => {
-  const [url] = useValue('schemaUrl', {
-    defaultValue: 'https://petstore3.swagger.io/api/v3/openapi.json',
-    label: 'Schema URL',
-    description: 'Full URL to an OpenAPI 3.x JSON schema',
-  });
-
-  const config: PlaygroundConfig = {
-    schemas: [
-      {
-        id: 'custom',
-        name: 'Custom Schema',
-        url,
-      },
-    ],
-    defaultSchemaId: 'custom',
-  };
-
-  return (
-    <div className="min-h-[600px]">
-      <Playground config={config} />
-    </div>
-  );
-};