@nxgt/material 3.93.0 → 3.94.0

package/dist/lib/components/ui/fields/index.d.ts

@@ -10,6 +10,7 @@ export * from './form-section/index.js';
 export * from './inline-edit/index.js';
 export * from './input-group-field/index.js';
 export * from './localized-text-fields/index.js';
+export * from './markdown-textarea-field/index.js';
 export * from './number-field/index.js';
 export * from './opening-hours/index.js';
 export * from './otp-field/index.js';

package/dist/lib/components/ui/fields/markdown-textarea-field/index.d.ts

@@ -0,0 +1,2 @@
+export * from './markdown-textarea-field.js';
+export * from './markdown-textarea-form-field.js';

package/dist/lib/components/ui/fields/markdown-textarea-field/markdown-preview.d.ts

@@ -0,0 +1,6 @@
+/** The body of the Preview tab: the rendered Markdown, or a hint when empty. */
+export declare function MarkdownPreview({ text, math, mermaid, }: {
+    text: string;
+    math: boolean;
+    mermaid: boolean;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/fields/markdown-textarea-field/markdown-syntax-help.d.ts

@@ -0,0 +1,4 @@
+/** The short syntax reminder under a Markdown textarea, collapsed by default. */
+export declare function MarkdownSyntaxHelp({ id }: {
+    id: string;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/fields/markdown-textarea-field/markdown-tabs.d.ts

@@ -0,0 +1,13 @@
+import { ReactNode } from 'react';
+type MarkdownTabsProps = {
+    /** The textarea (the Write tab). */
+    children: ReactNode;
+    text: string;
+    minRows: number;
+    math: boolean;
+    mermaid: boolean;
+    previewClassName?: string;
+};
+/** The Write / Preview tab list and its two panels. */
+export declare function MarkdownTabs({ children, text, minRows, math, mermaid, previewClassName, }: MarkdownTabsProps): import("react").JSX.Element;
+export {};

package/dist/lib/components/ui/fields/markdown-textarea-field/markdown-textarea-field.d.ts

@@ -0,0 +1,23 @@
+import { ComponentProps, ReactNode } from 'react';
+export type MarkdownTextareaProps = {
+    label?: ReactNode;
+    helperText?: ReactNode;
+    error?: boolean;
+    /** Minimum height of the textarea, in lines. Default 6. */
+    minRows?: number;
+    /** Show the character counter. Default: when `maxLength` is set. */
+    showCount?: boolean;
+    /** Render `$...$` and `$$...$$` with KaTeX in the preview. Default `true`. */
+    math?: boolean;
+    /** Draw ```` ```mermaid ```` fences as diagrams in the preview. Default `false`. */
+    mermaid?: boolean;
+    /** Show the collapsible syntax help. Default `true`. */
+    showHelp?: boolean;
+    /** Class of the preview panel. */
+    previewClassName?: string;
+} & ComponentProps<'textarea'>;
+/**
+ * A textarea for Markdown with a Write / Preview tab list. The preview is
+ * rendered with `Markdown` (raw HTML is never rendered).
+ */
+export declare function MarkdownTextareaField({ error, helperText, label, className, minRows, showCount, maxLength, math, mermaid, showHelp, previewClassName, value, defaultValue, onChange, ...props }: MarkdownTextareaProps): import("react").JSX.Element;

package/dist/lib/components/ui/fields/markdown-textarea-field/markdown-textarea-form-field.d.ts

@@ -0,0 +1,3 @@
+import { UseControllerProps } from 'react-hook-form';
+import { MarkdownTextareaProps } from './markdown-textarea-field.js';
+export declare function MarkdownTextareaFormField<T extends Record<string, any>>({ control, name, ...props }: Pick<UseControllerProps<T>, 'control' | 'name'> & Omit<MarkdownTextareaProps, 'name'>): import("react").JSX.Element;

package/dist/lib/components/ui/fields/markdown-textarea-field/use-text-value.d.ts

@@ -0,0 +1,6 @@
+import { ChangeEventHandler, ComponentProps } from 'react';
+/** The text of a textarea that may be controlled or not, for the counter and the preview. */
+export declare function useTextValue(value: ComponentProps<'textarea'>['value'], defaultValue: ComponentProps<'textarea'>['defaultValue'], onChange: ComponentProps<'textarea'>['onChange']): {
+    text: string;
+    handleChange: ChangeEventHandler<HTMLTextAreaElement>;
+};

package/dist/lib/components/ui/widgets/education/questions/index.d.ts

@@ -2,4 +2,4 @@ export { QuestionCard } from './question.js';
 export { answerParts, isAnswerCorrect, isAnswered, parseAnswerNumber, } from './question.utils.js';
 export { QuestionMediaView } from './question-media-view.js';
 export type { QuestionMediaFile, QuestionMediaViewProps, } from './question-media-view.types.js';
-export type { Question, QuestionAnswer, QuestionCodeField, QuestionImage, QuestionKind, QuestionMedia, QuestionMediaKind, QuestionOption, QuestionPoints, QuestionProps, QuestionVerdict, } from './types.js';
+export type { Question, QuestionAnswer, QuestionCodeField, QuestionExample, QuestionImage, QuestionKind, QuestionMedia, QuestionMediaKind, QuestionOption, QuestionPoints, QuestionProps, QuestionReference, QuestionVerdict, } from './types.js';

package/dist/lib/components/ui/widgets/education/questions/partials/question-hints.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Hints revealed one at a time. The button names the next one ("Show hint 2
+ * of 3"); the revealed hint takes the focus, and a status line keeps the count
+ * ("Hint 2 of 3") for a screen reader.
+ */
+export declare function QuestionHints({ hints, markdown, }: {
+    hints: string[];
+    markdown?: boolean;
+}): import("react").JSX.Element;

package/dist/lib/components/ui/widgets/education/questions/partials/question-reveal.d.ts

@@ -0,0 +1,13 @@
+import { Question } from '../types.js';
+/** Why each option is right or wrong, for the options that carry an `explanation`. */
+export declare function QuestionOptionExplanations({ question, }: {
+    question: Question;
+}): import("react").JSX.Element | null;
+/** The sources of a question: a labelled list, a link when there is a safe `url`. */
+export declare function QuestionReferences({ question }: {
+    question: Question;
+}): import("react").JSX.Element | null;
+/** A `code` question's examples: a table with an input and an expected column. */
+export declare function QuestionExamples({ question }: {
+    question: Question;
+}): import("react").JSX.Element | null;

package/dist/lib/components/ui/widgets/education/questions/partials/rich-text.d.ts

@@ -0,0 +1,17 @@
+import { ReactNode } from 'react';
+import { Question } from '../types.js';
+/**
+ * A question's text: plain, or Markdown with math when the question's
+ * `markdown` is on. Raw HTML is never rendered; mermaid is off. `inline` keeps
+ * it to phrasing content (the prompt, a label, a sentence).
+ */
+export declare function RichText({ markdown, inline, children, className, }: {
+    markdown?: boolean;
+    inline?: boolean;
+    children: string;
+    className?: string;
+}): import("react").JSX.Element;
+/** An option label: inline Markdown only when it is a string and the question asks for it. */
+export declare function richLabel(label: ReactNode, markdown?: boolean): ReactNode;
+/** The answer parts of a sentence ("Correct answer: …"): option labels as inline Markdown, typed answers as they are. */
+export declare function richParts(question: Question, parts: ReactNode[]): ReactNode[];

package/dist/lib/components/ui/widgets/education/questions/types.d.ts

@@ -38,6 +38,22 @@ export type QuestionOption = {
     description?: ReactNode;
     /** A picture: the options of the question become picture cards. */
     image?: QuestionImage;
+    /**
+     * Why this option is right or wrong, shown once the card is revealed (and in
+     * a `preview`), in a list under the question. Markdown when the question's
+     * `markdown` is on.
+     */
+    explanation?: string;
+};
+/** A source quoted in the reveal: a plain title, or a link when it has a `url`. */
+export type QuestionReference = {
+    title: string;
+    url?: string;
+};
+/** A visible example of a `code` question: what goes in and what must come out. */
+export type QuestionExample = {
+    input: string;
+    expected: string;
 };
 /** A choice id, the ids of a multi, the text (or the number as text) typed. */
 export type QuestionAnswer = string | string[] | null;
@@ -47,14 +63,37 @@ export type Question = {
     kind: QuestionKind;
     options?: QuestionOption[];
     correct?: string | string[];
+    /** Markdown when `markdown` is on. */
     explanation?: string;
     required?: boolean;
     placeholder?: string;
     exact?: boolean;
     /** A picture shown with the prompt; give it an `alt` unless decorative. */
     media?: QuestionMedia;
-    /** Shown on demand, behind a "Show hint" button. */
+    /**
+     * Draws the `prompt`, the string option labels, the `explanation`, the
+     * option explanations and the hints as Markdown with math (`$x^2$`), through
+     * the library's safe `Markdown` (raw HTML is not rendered, mermaid is off).
+     * Default `false`: plain text, as before.
+     */
+    markdown?: boolean;
+    /**
+     * Shown on demand, behind a "Show hint" button.
+     * @deprecated Use `hints`. Ignored when `hints` is not empty.
+     */
     hint?: string;
+    /**
+     * Hints revealed one at a time, in order, behind a "Show hint 1 of N" button
+     * that moves the focus to the hint it reveals. Hidden once the card is
+     * revealed.
+     */
+    hints?: string[];
+    /** Sources listed in the reveal; a `url` makes an external link (`rel="noopener noreferrer"`). */
+    references?: QuestionReference[];
+    /** `code`: the code field starts with this when there is no draft (`value` is null or undefined). */
+    starterCode?: string;
+    /** `code`: examples shown as a table (input, expected output) above the field. */
+    examples?: QuestionExample[];
     /** `number`: how far off an answer may be and still count (default 0). */
     tolerance?: number;
     /** `number`: the unit shown after the field ("km", "%"). */

package/dist/lib/i18n/resources/en/en.d.ts

@@ -375,6 +375,17 @@ export declare const en: {
             hint: string;
             "show-hint": string;
             "hide-hint": string;
+            rich: {
+                hints: string;
+                "show-next-hint": string;
+                "hint-n": string;
+                "option-explanations": string;
+                references: string;
+                "new-tab": string;
+                examples: string;
+                "example-input": string;
+                "example-expected": string;
+            };
             correct: string;
             incorrect: string;
             unanswered: string;
@@ -1356,6 +1367,19 @@ export declare const en: {
             unit: string;
             "unit-named": string;
         };
+        "markdown-textarea-field": {
+            write: string;
+            preview: string;
+            mode: string;
+            empty: string;
+            help: string;
+            "help-bold": string;
+            "help-list": string;
+            "help-code": string;
+            "help-inline-math": string;
+            "help-block-math": string;
+            "help-escape": string;
+        };
         "textarea-field": {
             count: string;
         };

package/dist/lib/i18n/resources/en/material.json.d.ts

@@ -365,6 +365,17 @@ declare const _default: {
 		"hint": "Hint",
 		"show-hint": "Show hint",
 		"hide-hint": "Hide hint",
+		"rich": {
+			"hints": "Hints",
+			"show-next-hint": "Show hint {number} of {total}",
+			"hint-n": "Hint {number} of {total}",
+			"option-explanations": "About each answer",
+			"references": "References",
+			"new-tab": "(external link)",
+			"examples": "Examples",
+			"example-input": "Input",
+			"example-expected": "Expected"
+		},
 		"correct": "Correct!",
 		"incorrect": "Not quite",
 		"unanswered": "Not answered",
@@ -1346,6 +1357,19 @@ declare const _default: {
 		"unit": "Unit",
 		"unit-named": "{label} unit"
 	},
+	"markdown-textarea-field": {
+		"write": "Write",
+		"preview": "Preview",
+		"mode": "Editor mode",
+		"empty": "Nothing to preview",
+		"help": "Formatting help",
+		"help-bold": "Bold",
+		"help-list": "List",
+		"help-code": "Code",
+		"help-inline-math": "Math in a line",
+		"help-block-math": "Math on its own line",
+		"help-escape": "A literal dollar sign"
+	},
 	"textarea-field": {
 		"count": "{count}/{max}"
 	},

package/dist/lib/i18n/resources/fr/fr.d.ts

@@ -375,6 +375,17 @@ export declare const fr: {
             hint: string;
             "show-hint": string;
             "hide-hint": string;
+            rich: {
+                hints: string;
+                "show-next-hint": string;
+                "hint-n": string;
+                "option-explanations": string;
+                references: string;
+                "new-tab": string;
+                examples: string;
+                "example-input": string;
+                "example-expected": string;
+            };
             correct: string;
             incorrect: string;
             unanswered: string;
@@ -1356,6 +1367,19 @@ export declare const fr: {
             unit: string;
             "unit-named": string;
         };
+        "markdown-textarea-field": {
+            write: string;
+            preview: string;
+            mode: string;
+            empty: string;
+            help: string;
+            "help-bold": string;
+            "help-list": string;
+            "help-code": string;
+            "help-inline-math": string;
+            "help-block-math": string;
+            "help-escape": string;
+        };
         "textarea-field": {
             count: string;
         };

package/dist/lib/i18n/resources/fr/material.json.d.ts

@@ -365,6 +365,17 @@ declare const _default: {
 		"hint": "Indice",
 		"show-hint": "Afficher l’indice",
 		"hide-hint": "Masquer l’indice",
+		"rich": {
+			"hints": "Indices",
+			"show-next-hint": "Afficher l’indice {number} sur {total}",
+			"hint-n": "Indice {number} sur {total}",
+			"option-explanations": "À propos de chaque réponse",
+			"references": "Références",
+			"new-tab": "(lien externe)",
+			"examples": "Exemples",
+			"example-input": "Entrée",
+			"example-expected": "Attendu"
+		},
 		"correct": "Bonne réponse !",
 		"incorrect": "Pas tout à fait",
 		"unanswered": "Sans réponse",
@@ -1346,6 +1357,19 @@ declare const _default: {
 		"unit": "Unité",
 		"unit-named": "Unité de {label}"
 	},
+	"markdown-textarea-field": {
+		"write": "Écrire",
+		"preview": "Aperçu",
+		"mode": "Mode de l'éditeur",
+		"empty": "Rien à prévisualiser",
+		"help": "Aide à la mise en forme",
+		"help-bold": "Gras",
+		"help-list": "Liste",
+		"help-code": "Code",
+		"help-inline-math": "Formule dans une ligne",
+		"help-block-math": "Formule sur sa propre ligne",
+		"help-escape": "Un signe dollar littéral"
+	},
 	"textarea-field": {
 		"count": "{count}/{max}"
 	},

package/dist/lib/i18n/resources/resources.d.ts

@@ -373,6 +373,17 @@ export declare const resources: {
                 hint: string;
                 "show-hint": string;
                 "hide-hint": string;
+                rich: {
+                    hints: string;
+                    "show-next-hint": string;
+                    "hint-n": string;
+                    "option-explanations": string;
+                    references: string;
+                    "new-tab": string;
+                    examples: string;
+                    "example-input": string;
+                    "example-expected": string;
+                };
                 correct: string;
                 incorrect: string;
                 unanswered: string;
@@ -1354,6 +1365,19 @@ export declare const resources: {
                 unit: string;
                 "unit-named": string;
             };
+            "markdown-textarea-field": {
+                write: string;
+                preview: string;
+                mode: string;
+                empty: string;
+                help: string;
+                "help-bold": string;
+                "help-list": string;
+                "help-code": string;
+                "help-inline-math": string;
+                "help-block-math": string;
+                "help-escape": string;
+            };
             "textarea-field": {
                 count: string;
             };
@@ -3932,6 +3956,17 @@ export declare const resources: {
                 hint: string;
                 "show-hint": string;
                 "hide-hint": string;
+                rich: {
+                    hints: string;
+                    "show-next-hint": string;
+                    "hint-n": string;
+                    "option-explanations": string;
+                    references: string;
+                    "new-tab": string;
+                    examples: string;
+                    "example-input": string;
+                    "example-expected": string;
+                };
                 correct: string;
                 incorrect: string;
                 unanswered: string;
@@ -4913,6 +4948,19 @@ export declare const resources: {
                 unit: string;
                 "unit-named": string;
             };
+            "markdown-textarea-field": {
+                write: string;
+                preview: string;
+                mode: string;
+                empty: string;
+                help: string;
+                "help-bold": string;
+                "help-list": string;
+                "help-code": string;
+                "help-inline-math": string;
+                "help-block-math": string;
+                "help-escape": string;
+            };
             "textarea-field": {
                 count: string;
             };