@timeax/form-palette 0.0.1

package/src/schema/input-field.ts

@@ -0,0 +1,260 @@
+// src/schema/input-field.ts
+
+import type { FieldSize, FieldDensity } from "@/variants/shared";
+
+/**
+ * Result type for validation hooks.
+ *
+ * Used by:
+ * - variant modules (`validate`)
+ * - per-field `onValidate` (InputField)
+ */
+export type ValidateResult =
+    | boolean // false = invalid, true = OK
+    | string // one error message
+    | string[] // multiple messages (first is used for display)
+    | null
+    | void; // null/void treated as "OK"
+
+/**
+ * Placement of the main label relative to the field control.
+ *
+ * This is a macro layout decision: where the label block lives
+ * compared to the input/control block.
+ */
+export type LabelPlacement = "top" | "left" | "right" | "hidden";
+
+/**
+ * Shared placement for helper slots relative to their *root*.
+ *
+ * Example:
+ *  - "above" → above the label root or input root
+ *  - "below" → below the label root or input root
+ *  - "left"  → left of the label root or input root
+ *  - "right" → right of the label root or input root
+ *  - "hidden" → not rendered
+ */
+export type SlotPlacement = "left" | "right" | "above" | "below" | "hidden";
+
+/**
+ * Placement of the sublabel relative to its root block.
+ */
+export type SublabelPlacement = SlotPlacement;
+
+/**
+ * Placement for the longer description block.
+ */
+export type DescriptionPlacement = SlotPlacement;
+
+/**
+ * Placement for helper text (typically small, subtle text).
+ */
+export type HelpTextPlacement = SlotPlacement;
+
+/**
+ * Placement for explicit error text (visual error copy).
+ */
+export type ErrorTextPlacement = SlotPlacement;
+
+/**
+ * Registry of all logical "slots" a field can render.
+ *
+ * Hosts can extend this via declaration merging, e.g.:
+ *
+ *   declare module "@/schema/input-field" {
+ *     interface FieldSlots {
+ *       charCounter: true;
+ *     }
+ *   }
+ */
+export interface FieldSlots {
+    /** The main label text. */
+    label: true;
+    /** Optional smaller label text. */
+    sublabel: true;
+    /** Longer, usually multi-line description. */
+    description: true;
+    /** Small helper text, usually subtle. */
+    helpText: true;
+    /** Error text (validation message) when present. */
+    errorText: true;
+    /** The actual control/input element. */
+    input: true;
+    /**tags */
+    tags: true;
+}
+
+/**
+ * Registry of logical "roots" / anchor blocks.
+ *
+ * Other slots are positioned relative to one of these.
+ */
+export interface FieldRoots {
+    /** Label root block. */
+    label: true;
+    /** Input/control root block. */
+    input: true;
+}
+
+export type FieldSlotId = keyof FieldSlots;
+export type FieldRootId = keyof FieldRoots;
+
+/**
+ * Map of which root each *non-root* slot belongs to.
+ *
+ * Example:
+ *   relativeRoots: {
+ *     sublabel: "label",
+ *     description: "input",
+ *     helpText: "input",
+ *     errorText: "input",
+ *   }
+ */
+export type RelativeRootsMap = Partial<
+    Record<
+        Exclude<FieldSlotId, FieldRootId>, // non-root slots only
+        FieldRootId
+    >
+>;
+
+/**
+ * Relative ordering of *non-root* slots per root.
+ *
+ * This is *not* about placement; it only decides "who comes first"
+ * when multiple slots share the same:
+ *   - root (label/input), and
+ *   - placement (above/below/left/right)
+ *
+ * Example:
+ *   ordering: {
+ *     input: ["errorText", "description", "helpText"],
+ *   }
+ *
+ * If description and helpText are both "below" the input, then the
+ * above config means:
+ *   - errorText (below input) first,
+ *   - then description (below input),
+ *   - then helpText (below input).
+ */
+export type FieldOrdering = Partial<
+    Record<FieldRootId, Exclude<FieldSlotId, FieldRootId>[]>
+>;
+
+/**
+ * Layout defaults for a field/variant.
+ *
+ * Variants can provide these as defaults; InputField merges them
+ * with per-field overrides.
+ *
+ * The high-level placement props remain the main public API.
+ * `relativeRoots` and `ordering` provide a lower-level layout graph
+ * that InputField can use to render slots relative to "label" or
+ * "input" in a predictable order.
+ */
+export interface FieldLayoutConfig {
+    /**
+     * Where to render the main label relative to the control.
+     */
+    labelPlacement?: LabelPlacement;
+
+    /**
+     * Where to render the sublabel relative to its root.
+     */
+    sublabelPlacement?: SublabelPlacement;
+
+    /**
+     * Where to render the description block relative to its root.
+     */
+    descriptionPlacement?: DescriptionPlacement;
+
+    /**
+     * Where to render helper text relative to its root.
+     */
+    helpTextPlacement?: HelpTextPlacement;
+
+    /**
+     * Where to render error text (if any) relative to its root.
+     */
+    errorTextPlacement?: ErrorTextPlacement;
+
+    /**Where to render the tags (if any) relative to ites root */
+    tagPlacement?: SlotPlacement;
+    /**
+     * Hint that the field should render inline with other controls.
+     */
+    inline?: boolean;
+
+    /**
+     * Hint that the field should stretch to the full available width.
+     */
+    fullWidth?: boolean;
+
+    /**
+     * Optional default size/density hints.
+     *
+     * These are advisory; variants/presets may override them.
+     */
+    defaultSize?: FieldSize;
+    defaultDensity?: FieldDensity;
+
+    /**
+     * Which root each non-root slot is attached to.
+     *
+     * If omitted, InputField can infer reasonable defaults, e.g.:
+     * - sublabel     → "label"
+     * - description  → "input"
+     * - helpText     → "input"
+     * - errorText    → "input"
+     */
+    relativeRoots?: RelativeRootsMap;
+
+    /**
+     * Relative ordering of non-root slots per root.
+     *
+     * Used only when multiple slots share the same
+     * root + placement combination.
+     */
+    ordering?: FieldOrdering;
+}
+
+/**
+ * Effective layout for a field after merging:
+ * - variant defaults, and
+ * - per-field overrides.
+ */
+export interface EffectiveFieldLayout extends FieldLayoutConfig {
+    /**
+     * Concrete size/density after merging defaults + overrides.
+     */
+    size?: FieldSize;
+    density?: FieldDensity;
+}
+
+/**
+ * Context passed to a variant's layout resolver.
+ *
+ * - `defaults`: layout defaults defined by the variant module.
+ * - `overrides`: only the layout keys explicitly set on <InputField />.
+ * - `props`: the raw <InputField /> props for this field.
+ *
+ * The resolver MUST respect host overrides: if a key is present in
+ * `overrides`, it should not change it.
+ */
+export interface LayoutResolveContext<T = unknown> {
+    defaults: FieldLayoutConfig;
+    overrides: Partial<FieldLayoutConfig>;
+    props: T;
+}
+
+/**
+ * Variant-level layout resolver.
+ *
+ * This allows variants to implement mapping rules such as:
+ * - "if labelPlacement is left ⇒ inline=true, error below, etc."
+ * while still allowing host overrides to win.
+ *
+ * Variants may also fill in `relativeRoots` and `ordering` to define
+ * how slots are attached to "label" vs "input" and in what relative
+ * order they should render.
+ */
+export type LayoutResolver<T = unknown> = (ctx: LayoutResolveContext<T>) => FieldLayoutConfig;

package/src/schema/variant.ts

@@ -0,0 +1,216 @@
+// src/schema/variant.ts
+
+import type { ComponentType } from "react";
+
+import type { Dict, CoreContext } from "@/schema/core";
+import type { Field } from "@/schema/field";
+import type {
+    FieldLayoutConfig,
+    LayoutResolver,
+    ValidateResult,
+} from "@/schema/input-field";
+import type { VariantBaseProps } from "@/variants/shared";
+import { TextVariantProps } from "@/variants/core/text";
+import { ShadcnNumberVariantProps } from "@/presets/shadcn-variants/number";
+import { ShadcnPhoneVariantProps } from "@/presets/shadcn-variants/phone";
+import { ShadcnColorVariantProps } from "@/presets/shadcn-variants/color";
+import { ShadcnPasswordVariantProps } from "@/presets/shadcn-variants/password";
+import {
+    DateVariantProps,
+    ShadcnDateVariantProps,
+} from "@/presets/shadcn-variants/date";
+import { ShadcnChipsVariantProps } from "@/presets/shadcn-variants/chips";
+import { ShadcnTextareaVariantProps } from "@/presets/shadcn-variants/textarea";
+import { ShadcnToggleVariantProps } from "@/presets/shadcn-variants/toggle";
+import { RadioItem, ShadcnRadioVariantProps } from "@/presets/shadcn-variants/radio";
+import { CheckboxVariantPublicValue, ShadcnCheckboxUiProps, ShadcnCheckboxVariantProps, ShadcnCheckboxVariantPublicProps } from "@/presets/shadcn-variants/checkbox";
+import { ShadcnSelectVariantProps } from "@/presets/shadcn-variants/select";
+import { ShadcnMultiSelectVariantProps } from "@/presets/shadcn-variants/multiselect";
+import { SliderValue } from "@/variants/core/slider";
+import { ShadcnSliderVariantProps } from "@/presets/shadcn-variants/slider";
+import { KeyValueMap, ShadcnKeyValueVariantProps } from "@/presets/shadcn-variants/keyvalue";
+import { ShadcnCustomVariantProps } from "@/presets/shadcn-variants/custom";
+import { ShadcnTreeSelectVariantProps } from "@/presets/shadcn-variants/treeselect";
+import { FileLike, ShadcnFileVariantProps } from "@/presets/shadcn-variants/file";
+import { ShadcnTextVariantProps } from "@/presets/shadcn-variants/text";
+import { SelectVariantProps } from "@/variants/core/select";
+
+/**
+ * Helper type for a single variant registry entry.
+ *
+ * Keeps the shape consistent and easy to extend via declaration merging.
+ */
+export interface VariantEntry<TValue, TProps> {
+    value: TValue;
+    props: TProps;
+}
+
+/**
+ * Base type-level variant registry.
+ *
+ * This is the **canonical mapping** used by:
+ * - InputFieldProps<K>
+ * - VariantModule<K>
+ *
+ * Hosts & presets extend it via declaration merging:
+ *
+ *   declare module "@/schema/variant" {
+ *     interface Variants {
+ *       select: VariantEntry<SelectValuePublic, SelectPropsPublic>;
+ *     }
+ *   }
+ */
+export interface Variants<H = unknown> {
+    /**
+     * Built-in "text" variant.
+     *
+     * Shadcn-based implementation lives in presets/shadcn-variants/text.tsx
+     */
+    text: VariantEntry<string | undefined, ShadcnTextVariantProps>;
+
+    /**
+     * Example scalar variant.
+     *
+     * You can repurpose this for "custom" or drop it later.
+     */
+    number: VariantEntry<number | undefined, ShadcnNumberVariantProps>;
+
+    phone: VariantEntry<string | number | undefined, ShadcnPhoneVariantProps>;
+    color: VariantEntry<string | undefined, ShadcnColorVariantProps>;
+    password: VariantEntry<string | undefined, ShadcnPasswordVariantProps>;
+
+    // Date is modeled as string for now (ISO/whatever your preset uses)
+    date: VariantEntry<string | undefined, ShadcnDateVariantProps>;
+
+    chips: VariantEntry<string[] | undefined, ShadcnChipsVariantProps>;
+    textarea: VariantEntry<string | undefined, ShadcnTextareaVariantProps>;
+    toggle: VariantEntry<boolean | undefined, ShadcnToggleVariantProps>;
+
+    radio: VariantEntry<unknown | undefined, ShadcnRadioVariantProps<unknown, RadioItem<unknown>>>
+    checkbox: VariantEntry<CheckboxVariantPublicValue, ShadcnCheckboxVariantPublicProps>
+    select: VariantEntry<string | number | undefined, SelectVariantProps>
+    'multi-select': VariantEntry<Array<string | number> | undefined, ShadcnMultiSelectVariantProps>,
+    slider: VariantEntry<SliderValue, ShadcnSliderVariantProps>
+    keyvalue: VariantEntry<KeyValueMap | undefined, ShadcnKeyValueVariantProps>
+    custom: VariantEntry<unknown | undefined, ShadcnCustomVariantProps>,
+    treeselect: VariantEntry<string | number | undefined, ShadcnTreeSelectVariantProps>,
+    file: VariantEntry<FileLike, ShadcnFileVariantProps>
+}
+
+
+
+/**
+ * Union of all variant keys.
+ */
+export type VariantKey = keyof Variants;
+
+/**
+ * Value type for a given variant key.
+ *
+ * Strongly drives autocomplete:
+ * - InputFieldProps<"text"> → TValue = string | undefined
+ */
+export type VariantValueFor<K extends VariantKey, H = unknown> = Variants<H>[K]["value"];
+
+/**
+ * Props type for a given variant key.
+ *
+ * Strongly drives autocomplete:
+ * - InputFieldProps<"text"> → props = TextVariantProps
+ */
+export type VariantPropsFor<K extends VariantKey, H = unknown> = Variants<H>[K]["props"];
+
+/**
+ * Signature for variant-level validation functions.
+ */
+export type VariantValidateFn<TValue, TProps> = (
+    value: TValue | undefined,
+    ctx: {
+        required?: boolean;
+        props: TProps;
+        field: Field;
+        form: CoreContext<Dict>;
+    }
+) => ValidateResult;
+
+/**
+ * Layout defaults for a variant.
+ *
+ * This extends FieldLayoutConfig, so it automatically includes:
+ * - placement props (labelPlacement, descriptionPlacement, etc.)
+ * - layout hints (inline, fullWidth, defaultSize/density)
+ * - layout graph (relativeRoots, ordering)
+ */
+export interface VariantLayoutDefaults extends FieldLayoutConfig { }
+
+/**
+ * Runtime module definition for a variant.
+ *
+ * IMPORTANT:
+ * - This is **tied directly** to the registry:
+ *     TValue = VariantValueFor<K>
+ *     TProps = VariantPropsFor<K>
+ *
+ *   So if you change the entry in `Variants`, both:
+ *     - <InputField variant="..." /> props
+ *     - The Variant component in the module
+ *   will see the updated types and IntelliSense matches everywhere.
+ *
+ * - For complex variants (select/multiselect):
+ *   you model the relationship via unions in `Variants["select"]`.
+ */
+export interface VariantModule<K extends VariantKey = VariantKey> {
+    /**
+     * Unique key for this variant, e.g. "text", "number", "select".
+     */
+    variant: K;
+
+    /**
+     * React component that renders the control.
+     *
+     * It receives:
+     * - VariantBaseProps<VariantValueFor<K>>
+     * - VariantPropsFor<K>
+     */
+    Variant: ComponentType<
+        VariantBaseProps<VariantValueFor<K>> & VariantPropsFor<K>
+    >;
+
+    /**
+     * Optional validation logic specific to this variant.
+     */
+    validate?: VariantValidateFn<
+        VariantValueFor<K>,
+        VariantPropsFor<K>
+    >;
+
+    /**
+     * Optional default layout hints for this variant.
+     */
+    defaults?: {
+        layout?: VariantLayoutDefaults;
+    };
+
+    /**
+     * Optional smart layout resolver.
+     *
+     * Must respect host overrides.
+     */
+    resolveLayout?: LayoutResolver<VariantPropsFor<K>>;
+
+    /**
+     * Optional metadata, useful for docs/inspectors.
+     */
+    meta?: {
+        label?: string;
+        description?: string;
+        tags?: string[];
+    };
+}
+
+/**
+ * Convenience alias when you want to be explicit:
+ *
+ *   const textModule: VariantModuleFor<"text"> = { ... }
+ */
+export type VariantModuleFor<K extends VariantKey> = VariantModule<K>;

package/src/variants/core/checkbox.tsx

@@ -0,0 +1,54 @@
+// src/variants/core/checkbox.ts
+
+import type { VariantModuleFor } from "@/schema/variant";
+import { ShadcnCheckboxVariant } from "@/presets/shadcn-variants/checkbox";
+import type {
+   ShadcnCheckboxVariantPublicProps,
+   CheckboxVariantPublicValue,
+} from "@/presets/shadcn-variants/checkbox";
+import type { VariantBaseProps } from "@/variants/shared";
+import { toggleLayoutDefaults } from "./toggle";
+
+/**
+ * Public props type you can import elsewhere:
+ *
+ *   import type { CheckboxVariantProps } from "@/variants/core/checkbox";
+ */
+export type CheckboxVariantProps = ShadcnCheckboxVariantPublicProps;
+
+/**
+ * Concrete Variant component type, if you need it:
+ *
+ *   VariantBaseProps<CheckboxVariantPublicValue> & CheckboxVariantProps
+ */
+type CheckboxVariantComponentProps =
+   VariantBaseProps<CheckboxVariantPublicValue> & CheckboxVariantProps;
+
+/**
+ * Runtime module for the "checkbox" variant.
+ *
+ * This wires the Shadcn preset into the core registry with sensible defaults.
+ */
+export const checkboxModule: VariantModuleFor<"checkbox"> = {
+   variant: "checkbox",
+
+   // ShadcnCheckboxVariant is generic; we fix it to the public aliases
+   // via this cast. At call sites you'll still get strong typing because
+   // the registry types know the concrete value/props.
+   Variant: ShadcnCheckboxVariant as unknown as React.ComponentType<CheckboxVariantComponentProps>,
+
+   resolveLayout({ props }) {
+      if (props.single) {
+         return toggleLayoutDefaults
+      }
+
+      return {};
+   },
+
+   meta: {
+      label: "Checkbox",
+      description:
+         "Single or group checkboxes with optional per-item tri-state support.",
+      tags: ["checkbox", "group", "boolean", "tri-state"],
+   },
+};

package/src/variants/core/chips.tsx

@@ -0,0 +1,22 @@
+import ShadcnChipsVariant from "@/presets/shadcn-variants/chips";
+import { VariantModuleFor } from "@/schema/variant";
+
+
+export const chipVariant: VariantModuleFor<"chips"> = {
+   variant: "chips",
+   Variant: ShadcnChipsVariant as any,
+   // Optional layout defaults – tweak as you like
+   defaults: {
+      layout: {
+         fullWidth: true,
+         // You can set defaultSize/defaultDensity here if you want:
+         // defaultSize: "md",
+         // defaultDensity: "normal",
+      },
+   },
+   meta: {
+      label: "Chips",
+      description: "Chips input allowing multiple selections.",
+      tags: ["chips", "multi-select", "tags"],
+   },
+}

package/src/variants/core/color.tsx

@@ -0,0 +1,16 @@
+// ———————————————————————————————
+// VariantModule wiring
+
+import { ShadcnColorVariant } from "@/presets/shadcn-variants/color";
+import { VariantModule } from "@/schema/variant";
+
+// ———————————————————————————————
+export const ColorVariantModule: VariantModule<"color"> = {
+   variant: "color",
+   Variant: ShadcnColorVariant,
+   meta: {
+      label: "Phone",
+      description: "Phone number input with country code and masking.",
+      tags: ["phone", "tel", "contact"],
+   },
+};

package/src/variants/core/custom.tsx

@@ -0,0 +1,18 @@
+// src/variants/core/custom.tsx
+
+import type { VariantModule } from "@/schema/variant";
+import { ShadcnCustomVariant } from "@/presets/shadcn-variants/custom";
+
+/**
+ * Core "custom" variant module.
+ *
+ * - Delegates all UI to ShadcnCustomVariant.
+ * - No layout defaults, no built-in validation.
+ * - Consumers can override layout via InputField props if needed.
+ */
+export const customVariant: VariantModule<"custom"> = {
+   variant: "custom",
+   Variant: ShadcnCustomVariant,
+};
+
+export default customVariant;

package/src/variants/core/date.tsx

@@ -0,0 +1,25 @@
+import ShadcnDateVariant from "@/presets/shadcn-variants/date";
+import { VariantModuleFor } from "@/schema/variant";
+
+
+export const dateVariant: VariantModuleFor<"date"> = {
+   variant: "date",
+   Variant: ShadcnDateVariant as any,
+
+   // Optional layout defaults – tweak as you like
+   defaults: {
+      layout: {
+         fullWidth: true,
+         // You can set defaultSize/defaultDensity here if you want:
+         // defaultSize: "md",
+         // defaultDensity: "normal",
+      },
+   },
+
+   meta: {
+      label: "Date",
+      description:
+         "Date input with calendar picker.",
+      tags: ["date", "calendar", "picker"],
+   },
+}

package/src/variants/core/file.tsx

@@ -0,0 +1,9 @@
+import ShadcnFileVariant from "@/presets/shadcn-variants/file";
+import { VariantModule } from "@/schema/variant";
+
+
+
+export const fileManagerModule: VariantModule<'file'> = {
+   Variant: ShadcnFileVariant as any,
+   variant: 'file'
+}

package/src/variants/core/keyvalue.tsx

@@ -0,0 +1,12 @@
+import ShadcnKeyValueVariant from "@/presets/shadcn-variants/keyvalue";
+import { VariantModule } from "@/schema/variant";
+
+
+export const keyValueModule: VariantModule<'keyvalue'> = {
+   variant: 'keyvalue',
+   Variant: ShadcnKeyValueVariant,
+
+   meta: {
+      label: ''
+   }
+} 

package/src/variants/core/multiselect.tsx

@@ -0,0 +1,28 @@
+
+
+// src/variants/multi-select.ts
+
+import type { VariantModule } from "@/schema/variant";
+import {
+   ShadcnMultiSelectVariant,
+   type ShadcnMultiSelectVariantProps,
+} from "@/presets/shadcn-variants/multiselect";
+
+export type MultiSelectValue = (string | number)[] | undefined;
+
+
+/**
+ * Variant module for "multi-select".
+ *
+ * No defaults / layout overrides here — layout is driven by InputField +
+ * host overrides, same as your other variants.
+ */
+export const multiSelectVariantModule: VariantModule<"multi-select"> = {
+   variant: "multi-select",
+   Variant: ShadcnMultiSelectVariant,
+   meta: {
+      
+   }
+};
+
+export default multiSelectVariantModule;