@omnitend/dashboard-for-laravel 0.33.1 → 0.34.0

package/dist/types/index.d.ts

@@ -308,6 +308,151 @@ export interface FieldDefinition {
      */
     show?: () => boolean;
 }
+/** 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;
+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.
@@ -329,3 +474,4 @@ export interface FormTab {
     /** Lazily mount tab content until first activated */
     lazy?: boolean;
 }
+export {};

package/dist/utils/formSchema.d.ts

@@ -0,0 +1,59 @@
+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 declare function defaultValueForType(type: FieldType): any;
+/**
+ * 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 declare function cloneDefault<TValue>(value: TValue): TValue;
+/**
+ * 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 declare function resolveFieldDefault(field: {
+    type: FieldType;
+    default?: any;
+}): any;
+/**
+ * Resolve a `MaybeFn<boolean>` predicate (`when` on a field or tab) against the
+ * live model. `undefined` yields `fallback` (the field/tab is unconditioned).
+ */
+export declare function resolvePredicate(when: MaybeFn<boolean> | undefined, model: any, fallback: boolean): boolean;
+/**
+ * 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 declare function isFieldVisible(field: {
+    when?: MaybeFn<boolean>;
+    show?: () => boolean;
+}, model: any): boolean;
+/**
+ * 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 declare function isSubmittableField(field: {
+    submit?: boolean;
+}): boolean;