@omnitend/dashboard-for-laravel 0.33.0 → 0.34.0

package/resources/js/components/extended/DXTableEditorModal.vue

@@ -47,6 +47,9 @@
             :form="form"
             :fields="fields"
             :tabs="tabs"
+            :layout="layout"
+            :label-cols="labelCols"
+            :card="card"
             :card-tabs="false"
             :context="item ?? undefined"
             :show-submit="false"
@@ -147,7 +150,7 @@
                         :disabled="form?.processing || loading"
                         @click="emit('delete')"
                     >
-                        Delete
+                        {{ deleteLabel }}
                     </DButton>
                 </div>
                 <div class="d-flex gap-2">
@@ -161,7 +164,7 @@
                         :disabled="form?.processing || loading"
                         @click="emit('save')"
                     >
-                        {{ isCreateMode ? 'Create' : 'Save Changes' }}
+                        {{ isCreateMode ? createLabel : saveLabel }}
                     </DButton>
                 </div>
             </div>
@@ -176,6 +179,7 @@ import DButton from "../base/DButton.vue";
 import DSpinner from "../base/DSpinner.vue";
 import DXForm from "./DXForm.vue";
 import type { EditTab } from "./DXTable.vue";
+import type { LabelCols } from "../../types";
 
 interface Props {
     /** Whether the modal is open (v-model:show). */
@@ -204,10 +208,38 @@ interface Props {
     pendingAction: 'save' | 'delete' | null;
     /** Delete endpoint — gates the Delete button. */
     deleteUrl?: string;
+    /** Field layout forwarded to the modal's DXForm (defaults handled upstream). */
+    layout?: 'vertical' | 'horizontal';
+    /** Label column width forwarded to DXForm (horizontal layout). */
+    labelCols?: LabelCols;
+    /** Wrap the modal form in a card (opt-in — off by default). */
+    card?: boolean;
+    /** Singular item noun for the default button labels (e.g. "customer"). */
+    itemName?: string;
+    /** Override the Save button label (edit mode). */
+    saveText?: string;
+    /** Override the Create button label (create mode). */
+    createText?: string;
+    /** Override the Delete button label. */
+    deleteText?: string;
 }
 
 const props = defineProps<Props>();
 
+// Title-case the singular item noun for button labels ("customer" → "Customer",
+// "sales order" → "Sales Order") — capitalize the first letter of each word.
+const capitalizedItem = computed(() => {
+    const noun = props.itemName?.trim() || 'item';
+    return noun.replace(/\b\w/g, (char) => char.toUpperCase());
+});
+
+// Buttons default to item-named copy ("Save Customer" / "Create Customer" /
+// "Delete Customer") — clearer than a generic "Save Changes" — overridable per
+// action. Falls back to "Save Item" etc. when no `itemName` is set.
+const saveLabel = computed(() => props.saveText ?? `Save ${capitalizedItem.value}`);
+const createLabel = computed(() => props.createText ?? `Create ${capitalizedItem.value}`);
+const deleteLabel = computed(() => props.deleteText ?? `Delete ${capitalizedItem.value}`);
+
 const emit = defineEmits<{
     /** v-model:show — the modal open state changed. */
     'update:show': [value: boolean];

package/resources/js/composables/defineForm.ts

@@ -1,5 +1,6 @@
 import { useForm, type UseFormReturn } from "./useForm";
-import type { FieldDefinition, FieldType } from "../types";
+import type { FieldDefinition } from "../types";
+import { resolveFieldDefault } from "../utils/formSchema";
 
 /**
  * Extended field definition that includes default value
@@ -30,35 +31,6 @@ export interface DefineFormReturn<TData extends Record<string, any>> {
     fields: FieldDefinition[];
 }
 
-/**
- * Helper to get default value for a field type
- */
-function getDefaultValueForType(type: FieldType): any {
-    switch (type) {
-        case "checkbox":
-        case "switch":
-            return false;
-        case "number":
-        case "currency":
-        case "percentage":
-            return 0;
-        case "repeater":
-        // Array-valued selections: checkbox-group previously fell through to
-        // the "" default, which is the wrong shape for an array model.
-        case "checkbox-group":
-        case "switch-list":
-            return [];
-        case "image":
-        case "file":
-            return null;
-        case "select":
-        case "radio":
-            return "";
-        default:
-            return "";
-    }
-}
-
 /**
  * Define a form with type-safe field definitions.
  * Reduces duplication by inferring initial values from field definitions.
@@ -75,22 +47,14 @@ export function defineForm<const TFields extends readonly FormFieldDefinition[]>
 ): DefineFormReturn<InferFormData<TFields>> {
     type FormData = InferFormData<TFields>;
 
-    // Extract initial data from field definitions.
-    //
-    // #125: `field.default ?? getDefaultValueForType(type)` cannot express a
-    // *null* default — a select whose "none" option is `value: null` (which is
-    // what the column stores) seeded '' (the type default), matched no option,
-    // and rendered blank. This is the same bug #122 fixed in DXTable. Decide on
-    // definedness, not nullishness, so null survives; an absent (or explicitly
-    // `undefined`) default still falls back to the type default rather than
-    // seeding `undefined`, which would drop the key from the JSON payload. This
-    // matches DXRepeater's `!== undefined` rule, so all seeding sites agree.
+    // Extract initial data from field definitions. Seeding (definedness over
+    // nullishness so a `null` default survives — #122/#125 — plus a type-aware
+    // fallback and deep-cloning) is the shared `resolveFieldDefault` rule, so
+    // every seeding site (defineForm / useResourceEditor / DXRepeater) agrees
+    // by construction (#134).
     const initialData = fieldDefinitions.reduce(
         (acc, field) => {
-            acc[field.key] =
-                field.default !== undefined
-                    ? field.default
-                    : getDefaultValueForType(field.type);
+            acc[field.key] = resolveFieldDefault(field);
             return acc;
         },
         {} as Record<string, any>,

package/resources/js/composables/useAsyncOptions.ts

@@ -0,0 +1,61 @@
+import { onMounted, ref, watch, type ComputedRef, type Ref } from "vue";
+import type { FieldDefinition, FieldOption } from "../types";
+
+/**
+ * Async option loading for a `DXField`: runs `field.optionsLoader` on mount and
+ * (when `field.reloadOptionsOnChange` is set) whenever the model changes,
+ * exposing the loaded options. A monotonic request token guards against
+ * out-of-order responses clobbering newer ones; loader failures are swallowed
+ * so the last good options (or the static `field.options` fallback) stay put.
+ *
+ * Extracted verbatim from DXField's inline logic (#135) — behaviour unchanged.
+ * `getField` is an accessor (props aren't destructurable without losing
+ * reactivity); `effectiveModel` is the model passed to the loader.
+ */
+export interface UseAsyncOptionsReturn {
+    /** Options returned by the most recent successful load, or null if none yet. */
+    loadedOptions: Ref<FieldOption[] | null>;
+    /** Trigger a load (no-op when the field has no `optionsLoader`). */
+    loadOptions: () => Promise<void>;
+}
+
+export function useAsyncOptions(
+    getField: () => FieldDefinition,
+    effectiveModel: ComputedRef<any> | Ref<any>,
+): UseAsyncOptionsReturn {
+    const loadedOptions = ref<FieldOption[] | null>(null);
+
+    // Monotonic token so out-of-order async responses can't clobber newer ones.
+    let optionsRequestToken = 0;
+
+    async function loadOptions(): Promise<void> {
+        const field = getField();
+        if (!field.optionsLoader) return;
+        const token = ++optionsRequestToken;
+        try {
+            const options = await field.optionsLoader(effectiveModel.value);
+            // Ignore a stale response superseded by a newer load.
+            if (token === optionsRequestToken) loadedOptions.value = options;
+        } catch (error) {
+            // Swallow loader failures: keep the last successfully loaded options
+            // (or the static `field.options` fallback when none have loaded yet).
+            if (token === optionsRequestToken) {
+                // eslint-disable-next-line no-console
+                console.error(
+                    `optionsLoader failed for field "${field.key}"`,
+                    error,
+                );
+            }
+        }
+    }
+
+    onMounted(() => {
+        void loadOptions();
+    });
+
+    if (getField().reloadOptionsOnChange) {
+        watch(effectiveModel, () => void loadOptions(), { deep: true });
+    }
+
+    return { loadedOptions, loadOptions };
+}

package/resources/js/composables/useResourceEditor.ts

@@ -2,6 +2,12 @@ import { computed, ref, type Ref } from "vue";
 import { api } from "../utils/api";
 import { useForm } from "./useForm";
 import { useToast } from "./useToast";
+import type { FieldDefinition } from "../types";
+import {
+    resolveFieldDefault,
+    isFieldVisible as isFieldVisibleFor,
+    isSubmittableField,
+} from "../utils/formSchema";
 
 /**
  * The subset of `DXTable`'s props the resource editor reads. Declared
@@ -11,7 +17,7 @@ import { useToast } from "./useToast";
  */
 export interface ResourceEditorProps<T = any> {
     /** Field definitions for the edit/create modal (enables edit-on-row-click). */
-    editFields?: any[];
+    editFields?: FieldDefinition[];
     /** Tab definitions — only their `key` is read here (DXForm consumes the rest). */
     editTabs?: Array<{ key: string }>;
     /** Modal title, or a function of the edited row. */
@@ -108,58 +114,38 @@ export function useResourceEditor<T = any>(
     // and auto-switching to the first tab with a validation error.
 
     /*
-     * A field's own starting value, used to seed a CREATE form and as the fallback
-     * when a row lacks the key (#122).
-     *
-     * `field.default ?? ''` can't express a NULL default: a select whose "none"
-     * option is `value: null` — which is what the column stores — seeds '' instead,
-     * matches no option, and renders blank. Presence, not nullishness, decides here
-     * too, so the create and edit paths agree about the same field.
-     */
-    const defaultValueFor = (field: any): any =>
-        Object.prototype.hasOwnProperty.call(field, 'default') ? field.default : '';
-
-    /*
-     * Seeding an EDIT form from a row (#117).
-     *
-     * `row[key] ?? field.default` is wrong: it can't tell "the row has no such key"
-     * from "the row's value IS null", so an explicitly-null column gets overwritten
-     * by the field's default — a value the user never saw, on a field they may not
-     * even be able to see. Presence, not nullishness, decides.
+     * Seeding an EDIT form from a row (#117): use the row's own value when it
+     * HAS the key (presence, not nullishness — an explicitly-null column must
+     * not be overwritten by the field's default), else the field's own default.
+     * The default comes from the shared `resolveFieldDefault` rule, so create
+     * and edit seeding agree with defineForm/DXRepeater (#134) — this path is
+     * now type-aware (an array field falls back to `[]`, not `''`).
      */
     const seedValueFor = (field: any, row: T): any => {
         if (Object.prototype.hasOwnProperty.call(row as any, field.key)) {
             return (row as any)[field.key];
         }
-        return defaultValueFor(field);
+        return resolveFieldDefault(field);
     };
 
     /*
-     * Whether a field is currently VISIBLE, by the same rule DXForm renders by
-     * (`when` + the legacy `show`), against the same model (context + live data).
-     * Kept in step with DXForm.isFieldVisible.
+     * The model field/tab predicates evaluate against: the edited row widened
+     * with the live form data (context + data), same as DXForm's `model`.
      */
     const editPredicateModel = computed(() => ({
         ...((selectedItem.value as any) ?? {}),
         ...(editForm.value?.data ?? {}),
     }));
 
-    const isEditFieldVisible = (field: any): boolean => {
-        const when = field.when;
-        const whenOk =
-            when === undefined
-                ? true
-                : typeof when === 'function'
-                  ? when(editPredicateModel.value)
-                  : when;
-        const showOk = field.show ? field.show() : true;
-        return whenOk && showOk;
-    };
+    // Visibility by the one shared rule (`when` + legacy `show`), against the
+    // edit model — see formSchema.isFieldVisible (#134).
+    const isEditFieldVisible = (field: any): boolean =>
+        isFieldVisibleFor(field, editPredicateModel.value);
 
     // Fields whose value actually belongs in the payload. A presentational field
     // (submit: false) renders but holds no data — see FieldDefinition.submit.
     const submittableEditFields = computed(() =>
-        (props.editFields ?? []).filter((field) => field.submit !== false),
+        (props.editFields ?? []).filter(isSubmittableField),
     );
 
     // Enforced at SUBMIT, not just at seeding: the modal still renders every field,
@@ -172,7 +158,7 @@ export function useResourceEditor<T = any>(
                     .filter(
                         (field) =>
                             // Presentational: lays the form out, holds no data (#110).
-                            field.submit === false ||
+                            !isSubmittableField(field) ||
                             // Hidden by `when` at submit time (#117). Submitting a field
                             // the user cannot see is a silent write — and with `default`
                             // set it writes a value they never chose. Omitting the key
@@ -299,13 +285,13 @@ export function useResourceEditor<T = any>(
         if (!editForm.value) {
             const formData: Record<string, any> = {};
             submittableEditFields.value.forEach(field => {
-                formData[field.key] = defaultValueFor(field);
+                formData[field.key] = resolveFieldDefault(field);
             });
             editForm.value = useForm(formData);
         } else {
             // Reset existing form to defaults
             submittableEditFields.value.forEach(field => {
-                editForm.value.data[field.key] = defaultValueFor(field);
+                editForm.value.data[field.key] = resolveFieldDefault(field);
             });
             editForm.value.clearErrors();
         }

package/resources/js/index.ts

@@ -113,6 +113,16 @@ export { useToast } from "./composables/useToast";
 
 // Utils
 export { api } from "./utils/api";
+// Pure form-schema helpers (#134) — the single source of defaulting, cloning,
+// predicate resolution, visibility and submission-eligibility.
+export {
+    defaultValueForType,
+    cloneDefault,
+    resolveFieldDefault,
+    resolvePredicate,
+    isFieldVisible,
+    isSubmittableField,
+} from "./utils/formSchema";
 
 // Types
 export type {
@@ -122,6 +132,27 @@ export type {
     FormTab,
     MaybeFn,
     OptionsLoader,
+    // Strict, discriminated field types (#131) — opt-in; canonical in a future
+    // major. `FieldDef` is the union; the rest are its per-type members.
+    FieldDef,
+    BaseFieldDef,
+    TextFieldDef,
+    PasswordFieldDef,
+    NumberFieldDef,
+    DateFieldDef,
+    CurrencyFieldDef,
+    PercentageFieldDef,
+    TextareaFieldDef,
+    SelectFieldDef,
+    AutocompleteFieldDef,
+    CheckboxFieldDef,
+    CheckboxGroupFieldDef,
+    SwitchFieldDef,
+    SwitchListFieldDef,
+    RadioFieldDef,
+    FileFieldDef,
+    ComponentFieldDef,
+    RepeaterFieldDef,
 } from "./types";
 
 export type {
@@ -149,6 +180,8 @@ export type {
     BTableProvider,
     EditTab,
     BTableProviderContext,
+    DXTableApiAdapter,
+    DXTableSource,
 } from "./components/extended/DXTable.vue";
 
 export type {

package/resources/js/types/index.ts

@@ -380,6 +380,237 @@ export interface FieldDefinition {
     show?: () => boolean;
 }
 
+// ───────────────────────────────────────────────────────────────────────────
+// Strict, discriminated field types (#131)
+//
+// The permissive `FieldDefinition` above lets every option appear on every
+// field type: `currencySymbol` compiles on a checkbox, `options` on a text
+// input, `component` without `type: "component"`. The types below are the
+// strict, `type`-keyed replacement — each variant permits only its own
+// options, so the compiler catches an invalid field config at the call site.
+//
+// ADDITIVE for now: `FieldDefinition` stays canonical and these are opt-in
+// (`import type { FieldDef } from "@omnitend/dashboard-for-laravel"`). A future
+// major (#131 Phase 3) makes `FieldDef` canonical and removes the permissive
+// interface with a codemod. **Until then, keep the two in step** — a prop added
+// to `FieldDefinition` must be added to the matching variant(s) below. The doc
+// comments live on `FieldDefinition`; variants stay terse to keep them aligned.
+//
+// Known limitation: the union rejects invalid FRESH object literals (excess
+// property checking — the common `fields: [{ type: "checkbox", … }]` call site),
+// but a PRE-DECLARED object with excess props (`const f = { type: "checkbox",
+// currencySymbol: "£" }`) stays structurally assignable. Full exclusivity would
+// need `never`-typed exclusion keys on every variant (or a StrictUnion helper) —
+// heavy machinery with confusing errors for marginal gain on an opt-in type, so
+// it's deliberately not done here.
+// ───────────────────────────────────────────────────────────────────────────
+
+/** Options common to every field variant (the non-`type`-specific props). */
+export interface BaseFieldDef {
+    key: string;
+    label?: MaybeFn<string>;
+    required?: boolean;
+    help?: string;
+    hint?: MaybeFn<string>;
+    info?: MaybeFn<string>;
+    class?: string;
+    inputProps?: Record<string, any>;
+    span?: boolean;
+    layout?: "vertical" | "horizontal";
+    labelCols?: LabelCols;
+    hideLabel?: boolean;
+    default?: any;
+    disabled?: MaybeFn<boolean>;
+    disabledWhen?: (model: any) => boolean;
+    readonly?: MaybeFn<boolean>;
+    plaintext?: MaybeFn<boolean>;
+    submit?: boolean;
+    when?: MaybeFn<boolean>;
+    show?: () => boolean;
+}
+
+/** Mixins shared by several variants (not exported — internal composition). */
+interface WithPlaceholder {
+    placeholder?: string;
+}
+interface WithNumericBounds {
+    step?: number | string;
+    min?: number | string;
+    max?: number | string;
+}
+interface WithSelectableOptions {
+    options?: FieldOption[];
+    optionsLoader?: OptionsLoader;
+    reloadOptionsOnChange?: boolean;
+}
+
+/** `text` / `email` / `url` / `tel` — a plain text-like `<input>`. */
+export interface TextFieldDef extends BaseFieldDef, WithPlaceholder {
+    type: "text" | "email" | "url" | "tel";
+}
+
+/** `password` — text input with an optional reveal (eye) toggle. */
+export interface PasswordFieldDef extends BaseFieldDef, WithPlaceholder {
+    type: "password";
+    revealable?: boolean;
+}
+
+/** `number` — numeric input with optional bounds. */
+export interface NumberFieldDef
+    extends BaseFieldDef,
+        WithPlaceholder,
+        WithNumericBounds {
+    type: "number";
+}
+
+/** `date` / `datetime` / `datetime-local` / `time` — native date/time controls.
+ *  `min`/`max`/`step` are valid on these inputs (e.g. `min="2024-01-01"`) and
+ *  DXField forwards them, so the variant permits them. */
+export interface DateFieldDef extends BaseFieldDef, WithNumericBounds {
+    type: "date" | "datetime" | "datetime-local" | "time";
+}
+
+/** `currency` — numeric input with a symbol affix and minor-unit handling. */
+export interface CurrencyFieldDef
+    extends BaseFieldDef,
+        WithPlaceholder,
+        WithNumericBounds {
+    type: "currency";
+    currencySymbol?: string;
+    decimals?: number;
+    minorUnits?: boolean;
+}
+
+/** `percentage` — numeric input shown as a 0–100 percentage. */
+export interface PercentageFieldDef
+    extends BaseFieldDef,
+        WithPlaceholder,
+        WithNumericBounds {
+    type: "percentage";
+    asFraction?: boolean;
+}
+
+/** `textarea` — multi-line text input. */
+export interface TextareaFieldDef extends BaseFieldDef, WithPlaceholder {
+    type: "textarea";
+    rows?: number;
+}
+
+/** `select` — dropdown; `searchable` upgrades it to a filterable select. */
+export interface SelectFieldDef
+    extends BaseFieldDef,
+        WithPlaceholder,
+        WithSelectableOptions {
+    type: "select";
+    searchable?: boolean;
+}
+
+/** `autocomplete` — free-text input with datalist suggestions. */
+export interface AutocompleteFieldDef
+    extends BaseFieldDef,
+        WithPlaceholder,
+        WithSelectableOptions {
+    type: "autocomplete";
+}
+
+/** `checkbox` — a single boolean checkbox. */
+export interface CheckboxFieldDef extends BaseFieldDef {
+    type: "checkbox";
+}
+
+/** `checkbox-group` — multiple checkboxes; model is an array of values. */
+export interface CheckboxGroupFieldDef
+    extends BaseFieldDef,
+        WithSelectableOptions {
+    type: "checkbox-group";
+}
+
+/** `switch` — a toggle with contextual on/off text and on-state colour. */
+export interface SwitchFieldDef extends BaseFieldDef {
+    type: "switch";
+    textWhenTrue?: MaybeFn<string>;
+    textWhenFalse?: MaybeFn<string>;
+    switchVariant?: "success" | "neutral";
+}
+
+/** `switch-list` — a labelled toggle row per option; model is an array. */
+export interface SwitchListFieldDef
+    extends BaseFieldDef,
+        WithSelectableOptions {
+    type: "switch-list";
+    switchVariant?: "success" | "neutral";
+}
+
+/** `radio` — a radio group. */
+export interface RadioFieldDef extends BaseFieldDef, WithSelectableOptions {
+    type: "radio";
+}
+
+/** `image` / `file` — file input (`image` also shows a preview). */
+export interface FileFieldDef extends BaseFieldDef {
+    type: "image" | "file";
+    accept?: string;
+}
+
+/** `component` — escape hatch rendering `field.component`. */
+export interface ComponentFieldDef extends BaseFieldDef {
+    type: "component";
+    /** Required on the strict variant: a `component` field with no component
+     *  falls through to the generic input branch, so the union enforces it. */
+    component: Component;
+}
+
+/** `repeater` — a nested, repeatable sub-form driven by `fields`. */
+export interface RepeaterFieldDef extends BaseFieldDef {
+    type: "repeater";
+    fields?: FieldDef[];
+    addLabel?: string;
+    minItems?: number;
+    maxItems?: number;
+    repeaterLayout?: "cards" | "table";
+    showRowIndex?: boolean;
+    softDeleteKey?: string;
+}
+
+/**
+ * Strict, discriminated replacement for `FieldDefinition`. Keyed on `type`,
+ * so each field only permits its own options. Opt-in today; canonical in a
+ * future major (#131). See the banner above.
+ */
+export type FieldDef =
+    | TextFieldDef
+    | PasswordFieldDef
+    | NumberFieldDef
+    | DateFieldDef
+    | CurrencyFieldDef
+    | PercentageFieldDef
+    | TextareaFieldDef
+    | SelectFieldDef
+    | AutocompleteFieldDef
+    | CheckboxFieldDef
+    | CheckboxGroupFieldDef
+    | SwitchFieldDef
+    | SwitchListFieldDef
+    | RadioFieldDef
+    | FileFieldDef
+    | ComponentFieldDef
+    | RepeaterFieldDef;
+
+/**
+ * Compile-time drift guard (#131): every strict variant must remain assignable
+ * to the permissive `FieldDefinition`. If a `FieldDef` variant grows a prop that
+ * `FieldDefinition` doesn't have (or types incompatibly), this fails to satisfy
+ * its `true` constraint and the build goes red. Purely type-level — no runtime.
+ * (The reverse direction — a prop added to `FieldDefinition` but forgotten on a
+ * variant — can't be asserted this way; the banner above is the reminder.)
+ */
+type _AssertTrue<T extends true> = T;
+// Exported (under an internal underscore name, not re-exported by the barrel)
+// only so `noUnusedLocals` treats it as used — its value is the constraint check.
+export type _FieldDefStaysASubset = _AssertTrue<
+    FieldDef extends FieldDefinition ? true : false
+>;
+
 /**
  * A tab in a tabbed form. Groups a subset of fields and can be shown
  * conditionally or lazily mounted.