@omnitend/dashboard-for-laravel 0.4.13 → 0.5.0

package/resources/js/types/index.ts

@@ -1,5 +1,16 @@
+import type { Component } from "vue";
+
 /**
- * Field types supported by OForm
+ * Field types supported by DXForm (and DXField, its per-field renderer).
+ *
+ * Text-like types render an `<input>`; the remainder render purpose-built
+ * controls:
+ * - `currency` / `percentage` — numeric input wrapped in an input-group
+ *   with a symbol affix.
+ * - `datetime` — alias for the native `datetime-local` control.
+ * - `image` / `file` — file input (`image` additionally shows a preview).
+ * - `component` — escape hatch that renders `field.component`.
+ * - `repeater` — nested, repeatable sub-form driven by `field.fields`.
  */
 export type FieldType =
     | "text"
@@ -10,11 +21,25 @@ export type FieldType =
     | "tel"
     | "date"
     | "datetime-local"
+    | "datetime"
     | "time"
+    | "currency"
+    | "percentage"
     | "textarea"
     | "select"
     | "checkbox"
-    | "radio";
+    | "radio"
+    | "image"
+    | "file"
+    | "component"
+    | "repeater";
+
+/**
+ * A value that may be supplied directly or computed from the live form
+ * model. Predicates receive the current model so fields can react to
+ * other fields (cross-field reactivity).
+ */
+export type MaybeFn<TValue> = TValue | ((model: any) => TValue);
 
 /**
  * Option for select or radio fields
@@ -26,7 +51,18 @@ export interface FieldOption extends Record<string, unknown> {
 }
 
 /**
- * Field definition for OForm
+ * Asynchronously resolves the options for a select/radio field from the
+ * current model (e.g. fetch a dependent list). Resolved on mount, and
+ * again on model change when `reloadOptionsOnChange` is set.
+ */
+export type OptionsLoader = (model: any) => Promise<FieldOption[]>;
+
+/**
+ * Field definition shared by every form renderer.
+ *
+ * DXForm and DXTable's edit modal honour `hint`, `span`, `when`,
+ * `readonly`, `disabledWhen`, function-valued `label`/`hint`, async
+ * options, the `component` escape hatch and nested `repeater` fields.
  */
 export interface FieldDefinition {
     /** Field key (must match form data key) */
@@ -35,8 +71,8 @@ export interface FieldDefinition {
     /** Field type */
     type: FieldType;
 
-    /** Field label (optional) */
-    label?: string;
+    /** Field label — string or a function of the form model */
+    label?: MaybeFn<string>;
 
     /** Placeholder text (optional) */
     placeholder?: string;
@@ -47,15 +83,123 @@ export interface FieldDefinition {
     /** Options for select or radio fields */
     options?: FieldOption[];
 
+    /**
+     * Asynchronously load options for select/radio fields. Takes
+     * precedence over `options` once resolved.
+     */
+    optionsLoader?: OptionsLoader;
+
+    /** Re-run `optionsLoader` whenever the form model changes. */
+    reloadOptionsOnChange?: boolean;
+
     /** Number of rows for textarea (default: 3) */
     rows?: number;
 
-    /** Help text displayed below field */
+    /** Step for numeric/currency/percentage inputs */
+    step?: number | string;
+
+    /** Min/max for numeric inputs */
+    min?: number | string;
+    max?: number | string;
+
+    /** Symbol shown for `currency` fields (default: the locale's, "£"). */
+    currencySymbol?: string;
+
+    /** `accept` attribute for `image`/`file` inputs (e.g. "image/*"). */
+    accept?: string;
+
+    /** Help text displayed below the field (always visible). */
     help?: string;
 
+    /**
+     * Hint text displayed below the field. Unlike `help`, may be a
+     * function of the model for dynamic hints.
+     */
+    hint?: MaybeFn<string>;
+
     /** CSS class for the form group */
     class?: string;
 
     /** Additional props to pass to the input component */
     inputProps?: Record<string, any>;
+
+    /**
+     * Render the field full-width with no label wrapper, delegating its
+     * content to the `#span(<key>)` slot. Useful for custom blocks.
+     */
+    span?: boolean;
+
+    /**
+     * Component rendered for `type: "component"` fields. Receives
+     * `modelValue`, `field`, `model` props and emits `update:modelValue`.
+     */
+    component?: Component;
+
+    /** Sub-field definitions for `type: "repeater"` fields. */
+    fields?: FieldDefinition[];
+
+    /**
+     * Default/initial value. Used by `defineForm` to seed form data and by
+     * repeaters to seed a freshly-added row's sub-fields. (`defineForm`'s
+     * `FormFieldDefinition` re-declares this as required for inference.)
+     */
+    default?: any;
+
+    /** Label for a repeater's "add row" button (default: "Add"). */
+    addLabel?: string;
+
+    /** Minimum / maximum number of repeater rows. */
+    minItems?: number;
+    maxItems?: number;
+
+    /** Disable the field (static or computed from the model). */
+    disabled?: MaybeFn<boolean>;
+
+    /**
+     * Disable the field based on the model. Retained for backwards
+     * compatibility with DXTable; prefer `disabled` with a function.
+     */
+    disabledWhen?: (model: any) => boolean;
+
+    /**
+     * Render the field read-only (static or computed). For controls
+     * without a native readonly state (select/checkbox/radio) this is
+     * applied as `disabled`.
+     */
+    readonly?: MaybeFn<boolean>;
+
+    /**
+     * Conditionally show or hide this field. When omitted the field is
+     * always visible. Boolean or a function of the form model; evaluated
+     * reactively for cross-field conditional fields.
+     */
+    when?: MaybeFn<boolean>;
+
+    /**
+     * Legacy no-argument visibility predicate. Retained for backwards
+     * compatibility; prefer `when`. When both are present, a field is
+     * visible only if both pass.
+     */
+    show?: () => boolean;
+}
+
+/**
+ * A tab in a tabbed form. Groups a subset of fields and can be shown
+ * conditionally or lazily mounted.
+ */
+export interface FormTab {
+    /** Unique key for this tab */
+    key: string;
+
+    /** Display label (optional, defaults to the key) */
+    label?: string;
+
+    /** Field keys (from the form's fields) to render in this tab */
+    fieldKeys: string[];
+
+    /** Conditional display — boolean or a function of the form model */
+    when?: MaybeFn<boolean>;
+
+    /** Lazily mount tab content until first activated */
+    lazy?: boolean;
 }

package/resources/js/utils/objectPath.ts

@@ -0,0 +1,59 @@
+/**
+ * Minimal dot-path get/set helpers used for nested form binding
+ * (e.g. repeater rows where a field value lives at `lines.0.price`).
+ *
+ * Paths are dot-separated; numeric segments index into arrays. Setting
+ * creates intermediate objects/arrays as needed so a fresh repeater row
+ * can be populated without pre-seeding the whole shape.
+ */
+
+type AnyRecord = Record<string, any>;
+
+/** Segments that could pollute Object.prototype if written through. */
+const BLOCKED_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
+
+/** Split a dot path into segments, ignoring empty segments. */
+function splitPath(path: string): string[] {
+    return path.split(".").filter((segment) => segment.length > 0);
+}
+
+/** Read the value at `path` within `target`, or `undefined` if absent. */
+export function getByPath(target: AnyRecord, path: string): any {
+    const segments = splitPath(path);
+    let current: any = target;
+    for (const segment of segments) {
+        if (current === null || current === undefined) return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+
+/**
+ * Write `value` at `path` within `target`, creating intermediate
+ * containers. A numeric next-segment creates an array; otherwise an
+ * object. Mutates `target` in place (form.data is reactive).
+ */
+export function setByPath(target: AnyRecord, path: string, value: any): void {
+    const segments = splitPath(path);
+    if (segments.length === 0) return;
+    // Never write through prototype-polluting segments.
+    if (segments.some((segment) => BLOCKED_SEGMENTS.has(segment))) return;
+
+    let current: any = target;
+    for (let index = 0; index < segments.length - 1; index += 1) {
+        const segment = segments[index];
+        const nextSegment = segments[index + 1];
+        const nextIsIndex = /^\d+$/.test(nextSegment);
+
+        if (
+            current[segment] === null ||
+            current[segment] === undefined ||
+            typeof current[segment] !== "object"
+        ) {
+            current[segment] = nextIsIndex ? [] : {};
+        }
+        current = current[segment];
+    }
+
+    current[segments[segments.length - 1]] = value;
+}