@timeax/form-palette 0.0.1

package/src/input/input-layout-graph.ts

@@ -0,0 +1,230 @@
+// src/input/input-layout-graph.ts
+
+import * as React from "react";
+
+import type {
+   FieldLayoutConfig,
+   FieldOrdering,
+   FieldRootId,
+   FieldSlotId,
+   RelativeRootsMap,
+   SlotPlacement,
+} from "@/schema/input-field";
+
+/**
+ * Helper slots are all non-root slots:
+ * - sublabel
+ * - description
+ * - helpText
+ * - errorText
+ */
+export type HelperSlotId = Exclude<FieldSlotId, FieldRootId>;
+
+export interface HelperSlot {
+   id: HelperSlotId;
+   root: FieldRootId;
+   placement: SlotPlacement;
+   content: React.ReactNode;
+}
+
+/**
+ * Accessor for a (root, placement) group.
+ *
+ * - `slots()` gives you the concrete HelperSlot[] (possibly empty).
+ * - `render(fn)` calls `fn(slots)` only if there are slots,
+ *   otherwise returns null (so React renders nothing).
+ */
+export interface SlotAccessor {
+   root: FieldRootId;
+   placement: SlotPlacement;
+
+   /**
+    * Concrete list of slots for this root + placement.
+    * May be an empty array.
+    */
+   slots(): HelperSlot[];
+
+   /**
+    * Render this group.
+    *
+    * If no slots are present, returns null so nothing is rendered.
+    *
+    * Example:
+    *   graph
+    *     .getSlotsFor("input", "below")
+    *     .render((slots) =>
+    *       slots.map((slot) =>
+    *         renderHelperSlot("input", slot, classes)
+    *       )
+    *     );
+    */
+   render(
+      renderFn: (slots: HelperSlot[]) => React.ReactNode
+   ): React.ReactNode;
+}
+
+/**
+ * Layout graph for helpers.
+ */
+export interface LayoutGraph {
+   helperSlots: HelperSlot[];
+
+   /**
+    * Get a slot accessor for a given root + placement.
+    */
+   getSlotsFor(
+      root: FieldRootId,
+      placement: SlotPlacement
+   ): SlotAccessor;
+}
+
+/**
+ * Default root attachment for helpers when layout.relativeRoots
+ * does not specify anything.
+ */
+const defaultRelativeRoots: RelativeRootsMap = {
+   sublabel: "label",
+   description: "input",
+   helpText: "input",
+   errorText: "input",
+};
+
+/**
+ * Default relative ordering per root when layout.ordering
+ * is not provided.
+ *
+ * Only governs *priority* when multiple helpers share the same
+ * root + placement. It does not decide the placement itself.
+ */
+const defaultOrdering: FieldOrdering = {
+   label: ["sublabel"],
+   input: ["errorText", "description", "helpText"],
+};
+
+function defaultPlacementFor(id: HelperSlotId): SlotPlacement {
+   if (id === "sublabel") {
+      // Typical: small label text to the right of the main label
+      return "right";
+   }
+   // For description/help/error, "below" the root is the usual default
+   return "below";
+}
+
+interface BuildLayoutGraphArgs {
+   layout: FieldLayoutConfig;
+   /**
+    * Raw contents for each helper slot.
+    * Undefined/null means "no slot".
+    */
+   sublabel?: React.ReactNode;
+   description?: React.ReactNode;
+   helpText?: React.ReactNode;
+   errorText?: React.ReactNode;
+   tags?: React.ReactNode;
+}
+
+/**
+ * Build a layout graph for helper slots given:
+ * - the effective layout (after variant defaults + overrides)
+ * - the actual content for each slot
+ */
+export function buildLayoutGraph(
+   args: BuildLayoutGraphArgs
+): LayoutGraph {
+   const { layout, sublabel, description, helpText, errorText, tags } = args;
+
+   const relativeRoots: RelativeRootsMap = {
+      ...defaultRelativeRoots,
+      ...(layout.relativeRoots ?? {}),
+   };
+
+   const ordering: FieldOrdering = {
+      ...defaultOrdering,
+      ...(layout.ordering ?? {}),
+   };
+
+   const helperSlots: HelperSlot[] = [];
+
+   const pushSlot = (
+      id: HelperSlotId,
+      content: React.ReactNode | undefined,
+      placement: SlotPlacement | undefined
+   ) => {
+      if (content === undefined || content === null) return;
+
+      const root: FieldRootId =
+         relativeRoots[id] ??
+         (id === "sublabel" ? "label" : "input");
+
+      const effectivePlacement: SlotPlacement =
+         placement ?? defaultPlacementFor(id);
+
+      if (effectivePlacement === "hidden") return;
+
+      helperSlots.push({
+         id,
+         root,
+         placement: effectivePlacement,
+         content,
+      });
+   };
+
+   pushSlot("sublabel", sublabel, layout.sublabelPlacement);
+   pushSlot("description", description, layout.descriptionPlacement);
+   pushSlot("helpText", helpText, layout.helpTextPlacement);
+   pushSlot("errorText", errorText, layout.errorTextPlacement);
+   pushSlot("tags", tags, layout.tagPlacement)
+
+   function makeAccessor(
+      root: FieldRootId,
+      placement: SlotPlacement
+   ): SlotAccessor {
+      // cache per accessor so multiple .slots()/.render() calls
+      // don't keep re-filtering
+      let cache: HelperSlot[] | null = null;
+
+      const compute = (): HelperSlot[] => {
+         if (cache) return cache;
+
+         const base = helperSlots.filter(
+            (s) => s.root === root && s.placement === placement
+         );
+
+         const order = ordering[root] ?? [];
+         if (!order.length) {
+            cache = base;
+            return cache;
+         }
+
+         cache = [...base].sort((a, b) => {
+            const ai = order.indexOf(a.id);
+            const bi = order.indexOf(b.id);
+
+            const aRank = ai === -1 ? Number.POSITIVE_INFINITY : ai;
+            const bRank = bi === -1 ? Number.POSITIVE_INFINITY : bi;
+
+            return aRank - bRank;
+         });
+
+         return cache;
+      };
+
+      return {
+         root,
+         placement,
+         slots: () => compute(),
+         render(renderFn) {
+            const slots = compute();
+            if (!slots.length) return null; // nothing rendered
+            return renderFn(slots);
+         },
+      };
+   }
+
+   return {
+      helperSlots,
+      getSlotsFor(root, placement) {
+         return makeAccessor(root, placement);
+      },
+   };
+}

package/src/input/input-props.ts

@@ -0,0 +1,190 @@
+// src/input/input-props.ts
+// noinspection DuplicatedCode
+
+import * as React from "react";
+
+import type { CoreContext, Dict } from "@/schema/core";
+import type { Field } from "@/schema/field";
+import type { FieldSize, FieldDensity, ChangeDetail } from "@/variants/shared";
+import type {
+    VariantKey,
+    VariantValueFor,
+    VariantPropsFor,
+} from "@/schema/variant";
+import type {
+    LabelPlacement,
+    SublabelPlacement,
+    DescriptionPlacement,
+    HelpTextPlacement,
+    ErrorTextPlacement,
+    ValidateResult,
+    SlotPlacement,
+} from "@/schema/input-field";
+
+/**
+ * Core, variant-agnostic props for InputField.
+ *
+ * @template TValue Logical value type for this field. Will be refined by
+ *                  variant typing (VariantValueFor<K>).
+ */
+export interface InputFieldBaseProps<TValue = unknown> {
+    // ─────────────────────────────────────────────
+    // Identity / wiring into the core runtime
+    // ─────────────────────────────────────────────
+
+    name?: string;
+    bind?: string;
+    groupId?: string;
+    shared?: string;
+    ignore?: boolean;
+    alias?: string
+    main?: boolean;
+    tags?: FieldTag[];
+    contain?: boolean
+
+    // ─────────────────────────────────────────────
+    // Chrome / description
+    // ─────────────────────────────────────────────
+
+    label?: React.ReactNode;
+    sublabel?: React.ReactNode;
+    description?: React.ReactNode;
+    helpText?: React.ReactNode;
+
+    /**
+     * Optional explicit error text to display.
+     *
+     * This is *visual* error copy. The actual validation state still
+     * lives in field.error / schema / onValidate.
+     */
+    errorText?: React.ReactNode;
+
+    /**
+     * Placement hints for label / sublabel / description / helpText / errorText.
+     *
+     * These are purely layout hints; actual behaviour is implemented
+     * by the preset / host component.
+     */
+    labelPlacement?: LabelPlacement;
+    sublabelPlacement?: SublabelPlacement;
+    descriptionPlacement?: DescriptionPlacement;
+    helpTextPlacement?: HelpTextPlacement;
+    errorTextPlacement?: ErrorTextPlacement;
+    tagPlacement?: SlotPlacement
+
+    // ─────────────────────────────────────────────
+    // State flags
+    // ─────────────────────────────────────────────
+
+    required?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+
+    size?: FieldSize;
+    density?: FieldDensity;
+
+    // ─────────────────────────────────────────────
+    // Layout hooks
+    // ─────────────────────────────────────────────
+
+    inline?: boolean;
+    fullWidth?: boolean;
+
+    // ─────────────────────────────────────────────
+    // Validation hooks
+    // ─────────────────────────────────────────────
+
+    onValidate?(
+        value: TValue | undefined,
+        field: Field,
+        form: CoreContext<Dict>
+    ): ValidateResult;
+
+    /**
+     * Per-field change hook at the InputField level.
+     *
+     * - `value` is what the variant is trying to set.
+     * - `detail` comes from the variant (`ChangeDetail`).
+     * - If you return `undefined`, the original value is used.
+     * - If you return *anything else*, that is what will be stored
+     *   in the core (and emitted to the form).
+     */
+    onChange?(e: {
+        value: TValue | undefined,
+        preventDefault(): void;
+        event?: React.SyntheticEvent;
+        readonly isDefaultPrevented?: boolean;
+        readonly detail: ChangeDetail
+    }): void;
+}
+
+
+export type Events<TRaw, TValue, TMeta> = {
+    onValidate?(
+        value: TValue | undefined,
+        field: Field,
+        form: CoreContext<Dict>
+    ): ValidateResult;
+
+    /**
+     * Per-field change hook at the InputField level.
+     *
+     * - `value` is what the variant is trying to set.
+     * - `detail` comes from the variant (`ChangeDetail`).
+     * - If you return `undefined`, the original value is used.
+     * - If you return *anything else*, that is what will be stored
+     *   in the core (and emitted to the form).
+     */
+    onChange?(e: {
+        value: TValue | undefined,
+        preventDefault(): void;
+        event?: React.SyntheticEvent;
+        readonly isDefaultPrevented?: boolean;
+        readonly detail: ChangeDetail<TMeta, TRaw>
+    }): void;
+}
+
+/**
+ * Public props for <InputField />.
+ *
+ * - `variant` selects the variant module.
+ * - All variant-specific props are merged directly into the field props
+ *   via `VariantPropsFor<K>`.
+ *
+ * NOTE: this is a type alias (not an interface) so we can safely intersect
+ * unions coming from VariantPropsFor<K> / VariantValueFor<K>.
+ */
+export type InputFieldProps<K extends VariantKey = VariantKey, H = unknown> =
+    InputFieldBaseProps<VariantValueFor<K, H>> &
+    VariantPropsFor<K, H> &
+    Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> & {
+        variant: K;
+        classes?: Partial<InputFieldClassNames>;
+    };
+
+export interface InputFieldClassNames {
+    root?: string;
+    labelRow?: string;
+    inlineRow?: string;
+    label?: string;
+    sublabel?: string;
+    description?: string;
+    helpText?: string;
+    error?: string;
+    group?: string;
+    content?: string;
+    variant?: string;
+    inlineInputColumn?: string
+    inlineLabelColumn?: string;
+    required?: string;
+    tag?: string
+}
+
+
+export interface FieldTag {
+    label: React.ReactNode;
+    icon?: React.ReactNode;
+    className?: string;
+    color?: string;   // text color
+    bgColor?: string; // background color
+}

package/src/lib/get-global-countries.ts

@@ -0,0 +1,87 @@
+import { PhoneCountry } from "@/presets/shadcn-variants/phone";
+
+// e.g. src/lib/get-global-countries.ts
+let cachedCountries: PhoneCountry[] | null = null;
+
+const DEFAULT_COUNTRIES: PhoneCountry[] = [
+   {
+      code: "NG",
+      label: "Nigeria",
+      dial: "234",
+      mask: "999 999 9999",
+      flag: "🇳🇬",
+   },
+   {
+      code: "US",
+      label: "United States",
+      dial: "1",
+      mask: "(999) 999-9999",
+      flag: "🇺🇸",
+   },
+   {
+      code: "GB",
+      label: "United Kingdom",
+      dial: "44",
+      mask: "9999 999 999",
+      flag: "🇬🇧",
+   },
+];
+
+cachedCountries = DEFAULT_COUNTRIES;
+let validatedOnce = false;
+
+function isPhoneCountry(value: unknown): value is PhoneCountry {
+   if (!value || typeof value !== "object") return false;
+
+   const v = value as Record<string, unknown>;
+
+   return (
+      typeof v.code === "string" &&
+      typeof v.label === "string" &&
+      typeof v.dial === "string" &&
+      typeof v.mask === "string"
+      // flag is optional & can be anything React can render, so we don't
+      // validate it beyond existence.
+   );
+}
+
+export function getGlobalCountryList(): PhoneCountry[] {
+   // If we've already validated & cached, just return it.
+   if (cachedCountries) return cachedCountries;
+
+   if (typeof window === "undefined") {
+      cachedCountries = [];
+      return cachedCountries;
+   }
+
+   const raw = window["form-palette"]?.countries;
+
+   if (!Array.isArray(raw)) {
+      if (!validatedOnce && process.env.NODE_ENV !== "production") {
+         console.warn(
+            "['form-palette'] window.'form-palette'.countries is not an array:",
+            raw,
+         );
+      }
+      validatedOnce = true;
+      cachedCountries = [];
+      return cachedCountries;
+   }
+
+   const result: PhoneCountry[] = [];
+
+   for (const item of raw) {
+      if (isPhoneCountry(item)) {
+         result.push(item);
+      } else if (process.env.NODE_ENV !== "production") {
+         console.warn(
+            "['form-palette'] Ignoring invalid PhoneCountry entry:",
+            item,
+         );
+      }
+   }
+
+   validatedOnce = true;
+   cachedCountries = result;
+   return result;
+}

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+    return twMerge(clsx(inputs));
+}