vira 32.0.0-beta.0 → 32.0.0

package/dist/util/vira-form-fields.d.ts

@@ -0,0 +1,145 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { type FullDate, type Timezone } from 'date-vir';
+import { type HtmlInterpolation } from 'element-vir';
+import { type ViraIconSvg } from '../icons/icon-svg.js';
+import { type ViraSelectOption } from './vira-select-option.js';
+/**
+ * Form field types for {@link ViraFormField}.
+ *
+ * @category Internal
+ */
+export declare enum ViraFormFieldType {
+    Text = "text",
+    /** Allows auto complete for _existing_ passwords used on this website (for login). */
+    ExistingPassword = "existing-password",
+    /** Allows auto complete for _new_ passwords used on this website (for login). */
+    NewPassword = "new-password",
+    /** Uses a password input without any attributes applied for auto complete hints. */
+    PlainPassword = "plain-password",
+    Email = "email",
+    Number = "number",
+    Select = "select",
+    Checkbox = "checkbox",
+    TextArea = "text-area",
+    Date = "date"
+}
+/**
+ * {@link ViraFormField} properties that are shared between all field types.
+ *
+ * @category Internal
+ */
+export type CommonViraFormFields = {
+    label: string;
+} & PartialWithUndefined<{
+    /** Applies a test id to the form field element. */
+    testId: string;
+    /**
+     * When `true`, visually indicates the form field as required and affects form validation.
+     *
+     * @default false
+     */
+    isRequired: boolean;
+    /**
+     * When `true`, marks this form field element with error styling.
+     *
+     * @default false
+     */
+    hasError: boolean;
+    /**
+     * When `true`, hides this form field entirely.
+     *
+     * @default false
+     */
+    isHidden: boolean;
+    /**
+     * When `true`, continues showing the form field but prevents edits.
+     *
+     * @default false
+     */
+    isDisabled: boolean;
+}>;
+/**
+ * An individual form field for {@link ViraFormFields}.
+ *
+ * @category Internal
+ */
+export type ViraFormField = ({
+    type: ViraFormFieldType.Text | ViraFormFieldType.ExistingPassword | ViraFormFieldType.NewPassword | ViraFormFieldType.PlainPassword | ViraFormFieldType.Email;
+    value: string | undefined;
+} & PartialWithUndefined<{
+    placeholder: string;
+    icon: ViraIconSvg;
+    isUsername: boolean;
+}> & CommonViraFormFields) | ({
+    type: ViraFormFieldType.Select;
+    value: string | undefined;
+    options: ReadonlyArray<Readonly<ViraSelectOption>>;
+} & PartialWithUndefined<{
+    placeholder: string;
+    icon: ViraIconSvg;
+}> & CommonViraFormFields) | ({
+    type: ViraFormFieldType.Checkbox;
+    value: boolean | undefined;
+    /**
+     * Label for the checkbox. Unlike other field types, this accepts arbitrary HTML so the
+     * checkbox's label slot can be filled with rich content.
+     */
+    label: HtmlInterpolation;
+} & PartialWithUndefined<{
+    /** The checkbox will be filled with a form selection color when it is checked. */
+    fillWhenChecked: boolean;
+    /** The checkbox will be filled with a form error color when it is unchecked. */
+    fillWhenUnchecked: boolean;
+}> & Omit<CommonViraFormFields, 'label'>) | ({
+    type: ViraFormFieldType.Number;
+    value: number | undefined;
+} & PartialWithUndefined<{
+    placeholder: string;
+    icon: ViraIconSvg;
+    min: number;
+    max: number;
+    step: number;
+}> & CommonViraFormFields) | ({
+    type: ViraFormFieldType.TextArea;
+    value: string | undefined;
+} & PartialWithUndefined<{
+    placeholder: string;
+    rows: number;
+    preventResize: boolean;
+}> & CommonViraFormFields) | ({
+    type: ViraFormFieldType.Date;
+    value: FullDate | undefined;
+} & PartialWithUndefined<{
+    /** Lower bound for selectable dates. Defaults to `1800-01-01` when omitted. */
+    min: FullDate;
+    /** Upper bound for selectable dates. Defaults to 10 years from now when omitted. */
+    max: FullDate;
+    /** Timezone used to interpret the selected date. Defaults to the user's timezone. */
+    timezone: Timezone;
+    /** Only show the date part of the selected date when in readonly mode. */
+    showDateOnly: boolean;
+    /** Only show the time part of the selected date when in readonly mode. */
+    showTimeOnly: boolean;
+}> & CommonViraFormFields);
+/**
+ * A collection of form fields for `ViraForm`.
+ *
+ * @category Internal
+ */
+export type ViraFormFields = Record<string, ViraFormField>;
+/**
+ * Appends a `'*'` to a label if it exist sand if it is required.
+ *
+ * @category Internal
+ */
+export declare function applyRequiredLabel(label: string | undefined, isRequired: boolean): string | undefined;
+/**
+ * Checks if all the {@link ViraFormField} entries in a given {@link ViraFormFields} are valid through
+ * the following checks:
+ *
+ * - Checks that required fields are provided (not `undefined`)
+ * - Ignores hidden fields
+ *
+ * @category Internal
+ */
+export declare function areFormFieldsValid(formFields: Readonly<ViraFormFields>): boolean;

package/dist/util/vira-form-fields.js

@@ -0,0 +1,66 @@
+import { check } from '@augment-vir/assert';
+import { addSuffix, getObjectTypedValues } from '@augment-vir/common';
+/**
+ * Form field types for {@link ViraFormField}.
+ *
+ * @category Internal
+ */
+export var ViraFormFieldType;
+(function (ViraFormFieldType) {
+    ViraFormFieldType["Text"] = "text";
+    /** Allows auto complete for _existing_ passwords used on this website (for login). */
+    ViraFormFieldType["ExistingPassword"] = "existing-password";
+    /** Allows auto complete for _new_ passwords used on this website (for login). */
+    ViraFormFieldType["NewPassword"] = "new-password";
+    /** Uses a password input without any attributes applied for auto complete hints. */
+    ViraFormFieldType["PlainPassword"] = "plain-password";
+    ViraFormFieldType["Email"] = "email";
+    ViraFormFieldType["Number"] = "number";
+    ViraFormFieldType["Select"] = "select";
+    ViraFormFieldType["Checkbox"] = "checkbox";
+    ViraFormFieldType["TextArea"] = "text-area";
+    ViraFormFieldType["Date"] = "date";
+})(ViraFormFieldType || (ViraFormFieldType = {}));
+/**
+ * Appends a `'*'` to a label if it exist sand if it is required.
+ *
+ * @category Internal
+ */
+export function applyRequiredLabel(label, isRequired) {
+    if (label) {
+        if (isRequired) {
+            return addSuffix({
+                value: label,
+                suffix: '*',
+            });
+        }
+        else {
+            return label;
+        }
+    }
+    else {
+        return undefined;
+    }
+}
+/**
+ * Checks if all the {@link ViraFormField} entries in a given {@link ViraFormFields} are valid through
+ * the following checks:
+ *
+ * - Checks that required fields are provided (not `undefined`)
+ * - Ignores hidden fields
+ *
+ * @category Internal
+ */
+export function areFormFieldsValid(formFields) {
+    return getObjectTypedValues(formFields).every((formField) => {
+        if (formField.isHidden || !formField.isRequired) {
+            return true;
+        }
+        else if (check.isString(formField.value)) {
+            return !!formField.value;
+        }
+        else {
+            return formField.value != undefined;
+        }
+    });
+}

package/dist/util/vira-json-schema.d.ts

@@ -0,0 +1,206 @@
+import { type JsonValue } from '@augment-vir/common';
+import { type JSONSchema } from 'json-schema-to-ts';
+/**
+ * The JSON Schema type used by `ViraJsonForm`. Re-exported from `json-schema-to-ts` so that callers
+ * can pass standard JSON Schema objects.
+ *
+ * @category Internal
+ */
+export type ViraJsonSchema = JSONSchema;
+/**
+ * A non-boolean JSON Schema object. Boolean schemas (`true` / `false`) are valid JSON Schemas but
+ * don't constrain the editor in useful ways, so we normalize them away during traversal.
+ *
+ * @category Internal
+ */
+export type ViraJsonSchemaObject = Exclude<ViraJsonSchema, boolean>;
+/**
+ * The JSON types supported by `ViraJsonForm`.
+ *
+ * @category Internal
+ */
+export declare enum ViraJsonType {
+    String = "string",
+    Number = "number",
+    Integer = "integer",
+    Boolean = "boolean",
+    Null = "null",
+    Object = "object",
+    Array = "array"
+}
+/**
+ * Human-friendly labels for each {@link ViraJsonType}.
+ *
+ * @category Internal
+ */
+export declare const viraJsonTypeLabels: Readonly<Record<ViraJsonType, string>>;
+/**
+ * Classifies a JSON value's runtime type. Note that {@link ViraJsonType.Integer} is never returned;
+ * it only appears in schemas. All numbers (whole or fractional) classify as
+ * {@link ViraJsonType.Number}, since JSON has no separate integer type at runtime.
+ *
+ * @category Internal
+ */
+export declare function getJsonType(value: JsonValue | undefined): ViraJsonType;
+/**
+ * Normalizes a schema to a non-boolean object form. `true` becomes an unconstrained schema (`{}`),
+ * `false` becomes `undefined` (nothing is allowed; treated as "no schema available").
+ *
+ * @category Internal
+ */
+export declare function normalizeSchema(schema: ViraJsonSchema | undefined): ViraJsonSchemaObject | undefined;
+/**
+ * Context used while resolving `$ref` entries against a root schema's `$defs` (or `definitions`)
+ * map. A stack of seen refs prevents infinite recursion from cyclical schemas.
+ *
+ * @category Internal
+ */
+export type SchemaResolveContext = {
+    root: ViraJsonSchemaObject | undefined;
+    seenRefs: ReadonlySet<string>;
+};
+/** @category Internal */
+export declare function createResolveContext(schema: ViraJsonSchema | undefined): SchemaResolveContext;
+/**
+ * Resolves a schema through `$ref` (via its root's `$defs`/`definitions`), returning the resolved
+ * schema and an updated resolve context. Non-ref schemas are returned as-is.
+ *
+ * @category Internal
+ */
+export declare function resolveSchema(schema: ViraJsonSchema | undefined, context: SchemaResolveContext): {
+    resolved: ViraJsonSchemaObject | undefined;
+    context: SchemaResolveContext;
+};
+/**
+ * Flattens `anyOf` / `oneOf` branches into a single list of non-union schemas so that the editor
+ * can treat them uniformly.
+ *
+ * @category Internal
+ */
+export declare function expandSchemaBranches(schema: ViraJsonSchema | undefined, context: SchemaResolveContext): ReadonlyArray<ViraJsonSchemaObject>;
+/**
+ * Computes the set of JSON types that a given schema allows.
+ *
+ * @category Internal
+ */
+export declare function getAllowedJsonTypes(schema: ViraJsonSchema | undefined, context: SchemaResolveContext): ReadonlyArray<ViraJsonType>;
+/** @category Internal */
+export declare function createDefaultForJsonType(type: ViraJsonType): JsonValue;
+/**
+ * Picks the first schema branch whose `type` contains (or is) the given JSON type. Used to narrow
+ * the schema when traversing into a concrete value.
+ *
+ * @category Internal
+ */
+export declare function pickBranchForType(schema: ViraJsonSchema | undefined, valueType: ViraJsonType, context: SchemaResolveContext): ViraJsonSchemaObject | undefined;
+/**
+ * Finds the sub-schema for a given object property key, considering `properties`,
+ * `patternProperties`, and `additionalProperties`.
+ *
+ * @category Internal
+ */
+export declare function getPropertySchema(parentSchema: ViraJsonSchema | undefined, key: string, context: SchemaResolveContext): ViraJsonSchema | undefined;
+/**
+ * Finds the sub-schema for an array item at a given index, considering tuple `items` arrays and
+ * `additionalItems` fallbacks.
+ *
+ * @category Internal
+ */
+export declare function getItemSchema(parentSchema: ViraJsonSchema | undefined, index: number, context: SchemaResolveContext): ViraJsonSchema | undefined;
+/**
+ * Returns the schema used when appending a new item to an array. Falls back to `additionalItems`
+ * when `items` is a tuple array and the new index is beyond the tuple's length.
+ *
+ * @category Internal
+ */
+export declare function getNewItemSchema(parentSchema: ViraJsonSchema | undefined, currentLength: number, context: SchemaResolveContext): ViraJsonSchema | undefined;
+/**
+ * Returns the schema used when adding an arbitrary new field to an object. When no schema is
+ * provided at all the editor is unconstrained, so additions are allowed; once a schema is provided,
+ * additions are only allowed when the schema explicitly opts in via `additionalProperties: true` or
+ * an `additionalProperties` sub-schema. This is stricter than JSON Schema's `true` default — UI
+ * authors must opt in.
+ *
+ * @category Internal
+ */
+export declare function getAdditionalPropertiesSchema(parentSchema: ViraJsonSchema | undefined, context: SchemaResolveContext): {
+    allowed: boolean;
+    schema: ViraJsonSchema | undefined;
+};
+/**
+ * Returns the `enum` values defined by any resolved branch of a schema. Aggregates across
+ * `anyOf`/`oneOf` branches and includes `const` values so the editor can offer them as a select.
+ *
+ * @category Internal
+ */
+export declare function getSchemaEnumValues(schema: ViraJsonSchema | undefined, context: SchemaResolveContext): ReadonlyArray<JsonValue> | undefined;
+/**
+ * Collects the string `enum`/`const` values declared by any branch of a schema, ignoring branches
+ * that declare no enum/const. Unlike {@link getSchemaEnumValues}, a schema that mixes an enum branch
+ * with a free-form branch still yields the enum values (rather than bailing out). Non-string enum
+ * entries are excluded.
+ *
+ * @category Internal
+ */
+export declare function getStringEnumValues(schema: ViraJsonSchema | undefined, context: SchemaResolveContext): ReadonlyArray<string>;
+/**
+ * Returns whether the schema permits an arbitrary (non-enum, non-const) string in any of its
+ * branches. Used alongside {@link getStringEnumValues} to detect fields that accept both a fixed set
+ * of enum options and free-form text.
+ *
+ * @category Internal
+ */
+export declare function allowsFreeformString(schema: ViraJsonSchema | undefined, context: SchemaResolveContext): boolean;
+/**
+ * Returns the list of required property names declared by the object branch of a schema.
+ *
+ * @category Internal
+ */
+export declare function getRequiredProperties(schema: ViraJsonSchema | undefined, context: SchemaResolveContext): ReadonlyArray<string>;
+/**
+ * Returns the `properties` map declared by the object branch of a schema, or an empty record when
+ * none is defined.
+ *
+ * @category Internal
+ */
+export declare function getDefinedProperties(schema: ViraJsonSchema | undefined, context: SchemaResolveContext): Readonly<Record<string, ViraJsonSchema>>;
+/**
+ * Reads the title of a schema's first resolved branch (for display purposes).
+ *
+ * @category Internal
+ */
+export declare function getSchemaTitle(schema: ViraJsonSchema | undefined, context: SchemaResolveContext): string | undefined;
+/**
+ * Validates a JSON value against the (loose) JSON Schema subset supported by `ViraJsonForm`.
+ * Returns a list of human-readable error messages; an empty array means the value is valid. Only
+ * the constraints understood by the editor (`type`, `required`, `properties`, `additionalProperties
+ * = false`, `items`, `enum`, `const`, `anyOf`, `oneOf`, `$ref`) are checked.
+ *
+ * @category Internal
+ */
+export declare function validateAgainstSchema(value: JsonValue, schema: ViraJsonSchema | undefined): ReadonlyArray<string>;
+/**
+ * Type of a JSON path element. `string` selects an object key; `number` selects an array index.
+ *
+ * @category Internal
+ */
+export type ViraJsonPath = ReadonlyArray<string | number>;
+/** @category Internal */
+export declare function pathToKey(path: ViraJsonPath): string;
+/**
+ * Returns a new JSON value where the value at `path` has been replaced with `newValue`.
+ *
+ * @category Internal
+ */
+export declare function setValueAtPath({ root, path, newValue, }: Readonly<{
+    root: JsonValue;
+    path: ViraJsonPath;
+    newValue: JsonValue;
+}>): JsonValue;
+/**
+ * Returns a new JSON value where the value at `path` has been removed. If `path` targets an object
+ * key, the key is deleted; if it targets an array index, the item is spliced out.
+ *
+ * @category Internal
+ */
+export declare function deleteValueAtPath(root: JsonValue, path: ViraJsonPath): JsonValue;