@omnitend/dashboard-for-laravel 0.33.1 → 0.35.0

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

@@ -110,9 +110,20 @@ export { default as DTooltip } from "./components/base/DTooltip.vue";
 export { useForm } from "./composables/useForm";
 export { defineForm } from "./composables/defineForm";
 export { useToast } from "./composables/useToast";
+export { useContainerWidth } from "./composables/useContainerWidth";
 
 // 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 +133,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 {
@@ -137,6 +169,12 @@ export type {
     DefineFormReturn,
 } from "./composables/defineForm";
 
+export type {
+    ContainerWidthTarget,
+    UseContainerWidthOptions,
+    UseContainerWidthReturn,
+} from "./composables/useContainerWidth";
+
 export type {
     ApiError,
     ApiResponse,
@@ -149,6 +187,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.

package/resources/js/utils/formSchema.ts

@@ -0,0 +1,126 @@
+/**
+ * Pure form-schema semantics — defaulting, cloning, predicate resolution,
+ * visibility, and submission-eligibility — extracted so the rule is defined
+ * ONCE and tested once (#134).
+ *
+ * These lived, drifted, in three-plus places: `defineForm`, `useResourceEditor`,
+ * `DXForm`, and `DXRepeater` each re-implemented seeding/visibility and were
+ * "kept in step" by hand — the exact shape of bug behind #117/#122/#125. Each
+ * copy had drifted: `DXRepeater`'s type map was missing the array-valued
+ * `checkbox-group`/`switch-list` cases, and `useResourceEditor` wasn't
+ * type-aware at all (a flat `""` fallback). Consolidating here fixes that drift.
+ *
+ * Everything is a plain function of its inputs (no Vue reactivity), so it unit
+ * tests directly.
+ */
+import { toRaw } from "vue";
+import type { FieldType, MaybeFn } from "../types";
+
+/**
+ * The canonical starting value for a field TYPE, used when a field declares no
+ * explicit `default`. Superset of the previous copies:
+ * - `checkbox` / `switch` → `false`
+ * - `number` / `currency` / `percentage` → `0`
+ * - `repeater` / `checkbox-group` / `switch-list` → `[]` (array-valued models)
+ * - `image` / `file` → `null`
+ * - everything else (text family, `select`, `radio`, `autocomplete`, …) → `""`
+ */
+export function defaultValueForType(type: FieldType): any {
+    switch (type) {
+        case "checkbox":
+        case "switch":
+            return false;
+        case "number":
+        case "currency":
+        case "percentage":
+            return 0;
+        case "repeater":
+        case "checkbox-group":
+        case "switch-list":
+            return [];
+        case "image":
+        case "file":
+            return null;
+        default:
+            return "";
+    }
+}
+
+/**
+ * Deep-clone a default so object/array defaults aren't shared BY REFERENCE
+ * across form instances or repeater rows (mutating one row would otherwise
+ * mutate the field's declared default and every sibling row).
+ *
+ * Mirrors `useForm`'s `deepClone`: `toRaw` unwraps a Vue reactive proxy, then
+ * `structuredClone` (which preserves Date/File/Map — a plain JSON round-trip
+ * would flatten a `Date` default to a string) with a JSON fallback for a
+ * residual nested proxy or otherwise-uncloneable value. This matters because
+ * `defineForm`/`useResourceEditor` now clone here BEFORE the value reaches
+ * `useForm`, so a lossy clone would corrupt a rich default the raw path used
+ * to preserve (#134 review).
+ */
+export function cloneDefault<TValue>(value: TValue): TValue {
+    if (value === null || typeof value !== "object") return value;
+    const raw = toRaw(value);
+    if (typeof structuredClone === "function") {
+        try {
+            return structuredClone(raw);
+        } catch {
+            // Reactive proxy or otherwise-uncloneable — fall through to JSON.
+        }
+    }
+    return JSON.parse(JSON.stringify(raw));
+}
+
+/**
+ * A field's starting value: its explicit `default` (deep-cloned) when one is
+ * DEFINED, else the type default. Definedness — not nullishness — decides, so a
+ * legitimate `null` default (e.g. a "none" select option whose value is `null`)
+ * survives instead of being replaced by the type default (#122/#125). An absent
+ * or explicitly-`undefined` default falls back to the type default rather than
+ * seeding `undefined`, which would drop the key from the JSON payload.
+ */
+export function resolveFieldDefault(field: {
+    type: FieldType;
+    default?: any;
+}): any {
+    return field.default !== undefined
+        ? cloneDefault(field.default)
+        : defaultValueForType(field.type);
+}
+
+/**
+ * Resolve a `MaybeFn<boolean>` predicate (`when` on a field or tab) against the
+ * live model. `undefined` yields `fallback` (the field/tab is unconditioned).
+ */
+export function resolvePredicate(
+    when: MaybeFn<boolean> | undefined,
+    model: any,
+    fallback: boolean,
+): boolean {
+    if (when === undefined) return fallback;
+    return typeof when === "function" ? when(model) : when;
+}
+
+/**
+ * Whether a field is VISIBLE against a model, by the one rule every renderer
+ * shares: the `when` predicate (default visible) AND the legacy no-arg `show`
+ * predicate. A field is visible only if both pass.
+ */
+export function isFieldVisible(
+    field: { when?: MaybeFn<boolean>; show?: () => boolean },
+    model: any,
+): boolean {
+    const whenOk = resolvePredicate(field.when, model, true);
+    const showOk = field.show ? field.show() : true;
+    return whenOk && showOk;
+}
+
+/**
+ * Whether a field's value belongs in the submitted payload. A presentational
+ * field (`submit: false`) — a header, an alert, an explanatory `span` block —
+ * renders but holds no data and must not be POSTed just because it was declared.
+ */
+export function isSubmittableField(field: { submit?: boolean }): boolean {
+    return field.submit !== false;
+}