@wssto2/vue-core 0.17.0 → 0.19.0

package/dist/form/codeEditor.d.ts

@@ -0,0 +1,27 @@
+import type { Extension } from "@codemirror/state";
+/** What `CodeField` edits. `liquid` is HTML with `{{ }}` and `{% %}` (and the `<script>` / `<style>` of the page highlighted as their own languages). */
+export type CodeLanguage = "liquid" | "html" | "css" | "javascript";
+/** A finding of the server's linter (`site lint-templates`) shown in the editor: the gutter and an underline. Lines and columns count from 1. */
+export interface CodeMarker {
+    line: number;
+    /** Without it the whole line is marked. */
+    column?: number;
+    severity: "error" | "warning";
+    message: string;
+}
+/**
+ * CodeMirror 6, every package an optional peer dependency (`npm i @codemirror/state @codemirror/view @codemirror/commands
+ * @codemirror/language @codemirror/lint`, and `@codemirror/lang-liquid` / `lang-html` / `lang-css` / `lang-javascript` for the
+ * languages in use). This file is the only place that imports them and only through `import()`: nothing loads until a `CodeField` shows.
+ */
+export declare function loadCodeEditor(): Promise<{
+    state: typeof import("@codemirror/state");
+    view: typeof import("@codemirror/view");
+    commands: typeof import("@codemirror/commands");
+    language: typeof import("@codemirror/language");
+    lint: typeof import("@codemirror/lint");
+    highlight: typeof import("@lezer/highlight");
+}>;
+export type CodeEditor = Awaited<ReturnType<typeof loadCodeEditor>>;
+/** The grammar of one language, loaded when it is first used. */
+export declare function loadCodeLanguage(name: CodeLanguage): Promise<Extension>;

package/dist/form/dynamic/DynamicForm.vue.d.ts

@@ -0,0 +1,46 @@
+import { ErrorBag } from "../errors";
+import type { FieldMessages } from "../validation";
+import { type LocaleMode } from "./localeMode";
+import type { ResourceSource } from "./resources";
+import type { FormSchema } from "./schema";
+/**
+ * A form generated from a typed schema (a content type's fields): each field's `kind` picks the control. It generates a form,
+ * nothing more: no page, no save; put it in an `EditorPage` and save the value yourself.
+ *
+ *   <DynamicForm v-model="values" :schema="schema" :locales="['hr', 'en']" :errors="form.errors.all()" :resources="media" />
+ *
+ * - **Value:** `Record<field key, value>`. A translatable text is `Record<locale, string>`; an image / document is a resource id,
+ *   a gallery a list of ids; a collection a list of row values.
+ * - **`visible_when`:** a field whose rule does not hold is not shown. It keeps its value, and an error under its key is not shown.
+ * - **`errors`:** go-core's field messages (`form.errors.all()`, or the `ErrorBag`), by field key; `images.0.title` reaches a row.
+ * - **`localeMode`:** `"perField"` (default) shows a language strip on each translatable field; `"form"` shows one switcher for
+ *   the whole form, which switches every translatable field at once.
+ */
+type __VLS_Props = {
+    schema: FormSchema;
+    modelValue?: Record<string, unknown>;
+    /** The languages of translatable fields. Default: the application's. */
+    locales?: readonly string[];
+    /** The language shown first, and the one a required translatable field needs. Default: the first. */
+    defaultLocale?: string;
+    errors?: FieldMessages | ErrorBag;
+    /** Reads the values instead of editing them. */
+    readonly?: boolean;
+    localeMode?: LocaleMode;
+    /** The media library of image, document and gallery fields, and of the picture button of rich text. */
+    resources?: ResourceSource;
+};
+declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:modelValue": (values: Record<string, unknown>) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onUpdate:modelValue"?: ((values: Record<string, unknown>) => any) | undefined;
+}>, {
+    errors: FieldMessages | ErrorBag;
+    modelValue: Record<string, unknown>;
+    readonly: boolean;
+    locales: readonly string[];
+    defaultLocale: string;
+    resources: ResourceSource;
+    localeMode: LocaleMode;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/form/dynamic/RepeatField.vue.d.ts

@@ -0,0 +1,47 @@
+import { type FieldProps } from "../field";
+import type { FieldMessages } from "../validation";
+import type { LocaleMode } from "./localeMode";
+import type { ResourceSource } from "./resources";
+import type { SchemaField } from "./schema";
+/**
+ * A repeatable group: rows the user adds, removes and moves, each a `DynamicForm` over `fields`. The value is the list of the
+ * rows' values. Errors of the rows arrive in the form's paths relative to this field (`0.title` is the first row's title).
+ *
+ *   <RepeatField v-model="form.slides" :fields="slideFields" label="Slides" />
+ */
+type __VLS_Props = FieldProps & {
+    /** The fields of each row. */
+    fields: readonly SchemaField[];
+    modelValue?: readonly Record<string, unknown>[];
+    locales?: readonly string[];
+    defaultLocale?: string;
+    /** Messages by path inside this field: `"0.title"`. */
+    errors?: FieldMessages;
+    resources?: ResourceSource;
+    addLabel?: string;
+    localeMode?: LocaleMode;
+};
+declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:modelValue": (rows: Record<string, unknown>[]) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onUpdate:modelValue"?: ((rows: Record<string, unknown>[]) => any) | undefined;
+}>, {
+    disabled: boolean;
+    name: string;
+    label: string;
+    error: string;
+    required: boolean;
+    presentation: "control" | "value";
+    errors: FieldMessages;
+    modelValue: readonly Record<string, unknown>[];
+    labelHidden: boolean;
+    hint: string;
+    editable: boolean;
+    lockedReason: string;
+    locales: readonly string[];
+    defaultLocale: string;
+    resources: ResourceSource;
+    addLabel: string;
+    localeMode: LocaleMode;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/form/dynamic/ResourceField.vue.d.ts

@@ -0,0 +1,38 @@
+import { type FieldProps } from "../field";
+import { type ResourceId, type ResourceSource } from "./resources";
+/**
+ * One resource, or several, chosen from the app's media library: the value is an id (`multiple`: a list of ids). It shows each
+ * as a picture from `source.thumbnail` and opens a `PickerModal` over `source.list(query)` to choose. The app owns the library;
+ * uploads are its too.
+ *
+ *   <ResourceField v-model="form.image" :source="media" label="Image" accept="image/*" />
+ *   <ResourceField v-model="form.gallery" :source="media" multiple label="Gallery" />
+ */
+type __VLS_Props = FieldProps & {
+    source: ResourceSource;
+    /** Several ids, kept in the order chosen. */
+    multiple?: boolean;
+    /** Passed to `source.list` as `query.accept`. */
+    accept?: string;
+    modelValue?: ResourceId | readonly ResourceId[] | null;
+};
+declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:modelValue": (value: ResourceId | ResourceId[] | null) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onUpdate:modelValue"?: ((value: ResourceId | ResourceId[] | null) => any) | undefined;
+}>, {
+    disabled: boolean;
+    name: string;
+    label: string;
+    error: string;
+    required: boolean;
+    presentation: "control" | "value";
+    accept: string;
+    modelValue: ResourceId | readonly ResourceId[] | null;
+    labelHidden: boolean;
+    hint: string;
+    editable: boolean;
+    lockedReason: string;
+    multiple: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/form/dynamic/ResourcePickerList.vue.d.ts

@@ -0,0 +1,12 @@
+import { type ResourceItem, type ResourceSource } from "./resources";
+/** The body of the resource picker: a search box, the app's rows as pictures, previous / next. Mounted afresh each time the dialog opens. */
+type __VLS_Props = {
+    source: ResourceSource;
+    accept?: string;
+};
+declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    select: (item: ResourceItem) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onSelect?: ((item: ResourceItem) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/form/dynamic/RichTextField.vue.d.ts

@@ -0,0 +1,40 @@
+import { type FieldProps } from "../field";
+import { type ResourceSource } from "./resources";
+/**
+ * Formatted text: headings, bold, italic, lists, links, a picture from the media library, optionally a video. The value is an
+ * HTML string ("" when empty). The editor is Quill 2, an optional peer dependency loaded when the field first shows
+ * (`npm i quill`); an application that never shows this field never loads it.
+ *
+ * The browser does not sanitise: the HTML is what the editor produced, and the server is the one that cleans it before storing.
+ *
+ *   <RichTextField v-model="form.body" :images="media" video label="Text" />
+ */
+type __VLS_Props = FieldProps & {
+    modelValue?: string;
+    /** The media library for the image button; without it there is no image button. Its `image` URL (else `thumbnail`) is the picture's `src`. */
+    images?: ResourceSource;
+    /** Shows the video embed button. */
+    video?: boolean;
+    placeholder?: string;
+};
+declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:modelValue": (html: string) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onUpdate:modelValue"?: ((html: string) => any) | undefined;
+}>, {
+    disabled: boolean;
+    placeholder: string;
+    name: string;
+    label: string;
+    video: boolean;
+    error: string;
+    required: boolean;
+    presentation: "control" | "value";
+    modelValue: string;
+    labelHidden: boolean;
+    hint: string;
+    editable: boolean;
+    lockedReason: string;
+    images: ResourceSource;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/form/dynamic/localeMode.d.ts

@@ -0,0 +1,5 @@
+import type { InjectionKey, Ref } from "vue";
+/** The language a form in `localeMode: "form"` is showing; its rows (`RepeatField`) follow it instead of showing a switcher of their own. */
+export declare const activeLocaleKey: InjectionKey<Readonly<Ref<string>>>;
+/** How translatable fields show their languages: a segment strip per field (`I18nField`), or one switcher for the whole form. */
+export type LocaleMode = "perField" | "form";

package/dist/form/dynamic/resources.d.ts

@@ -0,0 +1,34 @@
+/** An id the app's media library gives a resource (a picture, a document). */
+export type ResourceId = number | string;
+/** A row of the app's resource list; the picker needs nothing more. */
+export interface ResourceItem {
+    readonly id: ResourceId;
+    readonly name?: string;
+}
+/** What the picker asks the app's list for. `accept` is the field's `props.accept` (`"image/*"`). */
+export interface ResourceQuery {
+    readonly search: string;
+    /** From 1. */
+    readonly page: number;
+    readonly pageSize: number;
+    readonly accept?: string;
+}
+/** The part of a list page the picker reads; a `ListPage<ResourceItem>` fits. */
+export interface ResourcePage {
+    readonly rows: readonly ResourceItem[];
+    readonly lastPage: number;
+}
+/**
+ * Where resources come from: the app's, since only it knows its media library (folders, search, type filter go into
+ * `list`). A field holds ids; `thumbnail` turns one into a picture.
+ */
+export interface ResourceSource {
+    list(query: ResourceQuery, context: {
+        signal: AbortSignal;
+    }): Promise<ResourcePage>;
+    /** A URL with `{id}` in it: `"/media/{id}/thumb"`. */
+    thumbnail: string;
+    /** The URL of the full picture, for an image placed in rich text. Default: `thumbnail`. */
+    image?: string;
+}
+export declare const thumbnailUrl: (source: Pick<ResourceSource, "thumbnail">, id: ResourceId) => string;

package/dist/form/dynamic/schema.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The typed schema `DynamicForm`, `DynamicCollection` and `buildValidator` are generated from: the shape a content
+ * type's definition has in the API (snake_case keys, as the server sends them). It is data, not a page description:
+ * a list of fields with a kind, nothing about layout.
+ */
+/** The kinds a field can have. `image`, `document` and `gallery` hold ids of resources (one, one, several). */
+export type FieldKind = "text" | "textarea" | "rich_text" | "number" | "boolean" | "select" | "multi_select" | "date" | "datetime" | "image" | "document" | "gallery" | "collection";
+/** One test of a `visible_when` rule: the field named, compared with one operator. */
+export type VisibilityCondition = {
+    readonly field: string;
+    readonly eq: unknown;
+} | {
+    readonly field: string;
+    readonly ne: unknown;
+} | {
+    readonly field: string;
+    readonly in: readonly unknown[];
+} | {
+    readonly field: string;
+    readonly empty: true;
+} | {
+    readonly field: string;
+    readonly not_empty: true;
+};
+/** When a field shows: every condition of `all` holds, or at least one of `any`. See `evaluateVisibility`. */
+export type VisibilityRule = {
+    readonly all: readonly VisibilityCondition[];
+    readonly any?: undefined;
+} | {
+    readonly any: readonly VisibilityCondition[];
+    readonly all?: undefined;
+};
+export interface SelectChoice {
+    readonly value: string | number;
+    readonly label: string;
+}
+/** A rule of the whitelist a field may carry (the server's list, mirrored); `args` is the rule's parameters (`max`: `[150]`). */
+export interface FieldRule {
+    readonly rule: "required" | "min" | "max" | "email" | "url" | "regex";
+    readonly args?: readonly unknown[];
+}
+/** What a control shows, never what is valid (that is `validation`). */
+export interface SchemaFieldProps {
+    readonly placeholder?: string;
+    readonly hint?: string;
+    /** A resource field: the kinds the picker lists (`"image/*"`), passed to the app's `list(query)`. */
+    readonly accept?: string;
+    /** A `textarea`'s rows. */
+    readonly rows?: number;
+    /** A `rich_text` field: show the video embed button. */
+    readonly video?: boolean;
+    /** A `collection` field: the label of its add button. */
+    readonly addLabel?: string;
+}
+export interface SchemaField {
+    readonly key: string;
+    readonly kind: FieldKind;
+    readonly label: string;
+    readonly required?: boolean;
+    /** Text kinds only: the value is `Record<locale, string>`. */
+    readonly translatable?: boolean;
+    readonly props?: SchemaFieldProps;
+    /** `select` and `multi_select`. */
+    readonly options?: readonly SelectChoice[];
+    /** Whitelisted rules besides `required`: `min`/`max` (a text's length, a number's value, a list's size), `email`, `url`, `regex`. */
+    readonly validation?: readonly FieldRule[];
+    readonly visible_when?: VisibilityRule;
+    /** `collection` only: the fields of each row. */
+    readonly children?: readonly SchemaField[];
+}
+export interface FormSchema {
+    readonly fields: readonly SchemaField[];
+}

package/dist/form/dynamic/validator.d.ts

@@ -0,0 +1,30 @@
+import type * as Zod from "zod";
+import type { FormValidator } from "../validation";
+import type { FormSchema } from "./schema";
+export interface SchemaValidatorOptions {
+    /**
+     * The `zod` module (`import * as zod from "zod"`). Passed in, not imported here, so an application that never validates a
+     * schema does not need Zod installed: it is an optional peer, and an import in this file would load it with `@wssto2/vue-core/form`.
+     */
+    zod: typeof Zod;
+    /**
+     * Texts that replace Zod's. Without them the issues carry Zod's own messages, which `zodErrorMap(application)` words in the
+     * application's language (a missing value reads as `validation_errors.required`).
+     */
+    messages?: Partial<Record<"required" | "email" | "url" | "regex" | "type", string>>;
+    /** The language a required translatable text needs. Default: any language written. */
+    defaultLocale?: string;
+}
+/**
+ * A validator for a schema, with the shape `useForm` takes (`safeParse`), built on Zod 4. It checks what the server will: `required`,
+ * the type of each kind, `min` / `max` (a text's length, a number's value, the size of a list or collection), `email`, `url`,
+ * `regex`, and the rows of a collection. A field whose `visible_when` does not hold is skipped, and left out of the output, as is a
+ * key the schema does not list. The server is authoritative; this only saves the round trip.
+ *
+ *   const validator = buildValidator(schema, { zod });
+ *   const form = useForm({ defaults, validator });
+ *
+ * A `regex` argument must be valid for both JavaScript and Go's RE2 (no look-around, no back-references). A rule the schema
+ * words wrongly (`max` without a number) throws when the validator is built, not on the user's first keystroke.
+ */
+export declare function buildValidator(schema: FormSchema, options: SchemaValidatorOptions): FormValidator<Record<string, unknown>>;

package/dist/form/dynamic/visibility.d.ts

@@ -0,0 +1,12 @@
+import type { VisibilityRule } from "./schema";
+/** Empty means not entered: null, undefined, "", an empty list, and an object (a translated text) with no non-blank entry. `false` and `0` are values. */
+export declare function isEmptyValue(value: unknown): boolean;
+/**
+ * Whether a field with this `visible_when` rule shows, given the form's values. A pure function; the server evaluates the same
+ * rule (a hidden field is neither required nor validated) and both run `test-data/content/visibility.json`.
+ *
+ * - no rule, or a rule with no conditions: visible;
+ * - `all`: every condition holds; `any`: at least one does;
+ * - a malformed condition (unknown operator, `in` without a list) is skipped, and a rule left with none is visible: a broken rule never hides a field for good.
+ */
+export declare function evaluateVisibility(rule: VisibilityRule | null | undefined, values: Readonly<Record<string, unknown>>): boolean;

package/dist/form/index.d.ts

@@ -81,3 +81,16 @@ export type { StepDefinition, StepDialogBinding, StepDraftOptions, StepFlow, Ste
 export { default as StepForm } from "./StepForm.vue";
 export { default as StepNavigation } from "./StepNavigation.vue";
 export { default as StepProgress } from "./StepProgress.vue";
+export { default as DynamicForm } from "./dynamic/DynamicForm.vue";
+export { default as RepeatField } from "./dynamic/RepeatField.vue";
+export { default as ResourceField } from "./dynamic/ResourceField.vue";
+export { default as RichTextField } from "./dynamic/RichTextField.vue";
+export { default as CodeField } from "./CodeField.vue";
+export type { CodeLanguage, CodeMarker } from "./codeEditor";
+export { evaluateVisibility, isEmptyValue } from "./dynamic/visibility";
+export { buildValidator } from "./dynamic/validator";
+export type { SchemaValidatorOptions } from "./dynamic/validator";
+export type { LocaleMode } from "./dynamic/localeMode";
+export { thumbnailUrl } from "./dynamic/resources";
+export type { ResourceId, ResourceItem, ResourcePage, ResourceQuery, ResourceSource } from "./dynamic/resources";
+export type { FieldKind, FieldRule, FormSchema, SchemaField, SelectChoice, VisibilityCondition, VisibilityRule } from "./dynamic/schema";