@nfcard/validation 0.24.0 → 0.25.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _nfcard_types from '@nfcard/types';
-import { CardAsset, CardElement, ElementTransform, ProfileLayout } from '@nfcard/types';
+import { CardAsset, CardElement, ElementTransform, ProfileObjectKind, ProfileLayout } from '@nfcard/types';
 import { z } from 'zod';
 
 /**
@@ -145,17 +145,17 @@ declare const textObjectStyleSchema: z.ZodObject<{
     fontKey?: string | undefined;
     italic?: boolean | undefined;
     underline?: boolean | undefined;
-    color?: string | undefined;
-    sizeStep?: "sm" | "md" | "lg" | undefined;
     align?: "start" | "center" | undefined;
+    sizeStep?: "sm" | "md" | "lg" | undefined;
+    color?: string | undefined;
 }, {
     weight?: "bold" | "normal" | undefined;
     fontKey?: string | undefined;
     italic?: boolean | undefined;
     underline?: boolean | undefined;
-    color?: string | undefined;
-    sizeStep?: "sm" | "md" | "lg" | undefined;
     align?: "start" | "center" | undefined;
+    sizeStep?: "sm" | "md" | "lg" | undefined;
+    color?: string | undefined;
 }>;
 declare const imageObjectStyleSchema: z.ZodObject<{
     crop: z.ZodOptional<z.ZodObject<{
@@ -193,16 +193,74 @@ declare const imageObjectStyleSchema: z.ZodObject<{
     borderColor?: string | undefined;
     borderPx?: number | undefined;
 }>;
-declare const buttonObjectStyleSchema: z.ZodObject<{
+/**
+ * Contact rows and social chips: text minus `align` and `sizeStep`. Row
+ * alignment is the template's grid; and a row is a COMPOUND (label/value
+ * spans with their own px sizes), so no wrapper-level em can scale it
+ * without destroying the internal hierarchy — either would be a
+ * stored-but-dead field.
+ */
+declare const rowTextStyleSchema: z.ZodObject<Omit<{
+    color: z.ZodOptional<z.ZodString>;
+    sizeStep: z.ZodOptional<z.ZodEnum<["sm", "md", "lg"]>>;
+    align: z.ZodOptional<z.ZodEnum<["start", "center"]>>;
+    weight: z.ZodOptional<z.ZodEnum<["normal", "bold"]>>;
+    italic: z.ZodOptional<z.ZodBoolean>;
+    underline: z.ZodOptional<z.ZodBoolean>;
+    fontKey: z.ZodOptional<z.ZodString>;
+}, "align" | "sizeStep">, "strict", z.ZodTypeAny, {
+    weight?: "bold" | "normal" | undefined;
+    fontKey?: string | undefined;
+    italic?: boolean | undefined;
+    underline?: boolean | undefined;
+    color?: string | undefined;
+}, {
+    weight?: "bold" | "normal" | undefined;
+    fontKey?: string | undefined;
+    italic?: boolean | undefined;
+    underline?: boolean | undefined;
+    color?: string | undefined;
+}>;
+/** Label styling (the text vocabulary's `color`/`weight`/`italic`/`fontKey`,
+ *  DERIVED so the validators stay in lockstep) + `bg` fill. No `sizeStep`
+ *  in v1 — button geometry is the template's. `variant` is GONE (0.24.0
+ *  accepted it and the render did style it): NO SURFACE COULD EVER WRITE IT
+ *  — the toolbar exposes no variant control and none is planned — and a
+ *  stored-but-unwritable field is dead weight on every future vintage. No
+ *  deployed tag ever accepted one, so nothing stored carries it. */
+declare const buttonObjectStyleSchema: z.ZodObject<Pick<{
+    color: z.ZodOptional<z.ZodString>;
+    sizeStep: z.ZodOptional<z.ZodEnum<["sm", "md", "lg"]>>;
+    align: z.ZodOptional<z.ZodEnum<["start", "center"]>>;
+    weight: z.ZodOptional<z.ZodEnum<["normal", "bold"]>>;
+    italic: z.ZodOptional<z.ZodBoolean>;
+    underline: z.ZodOptional<z.ZodBoolean>;
+    fontKey: z.ZodOptional<z.ZodString>;
+}, "weight" | "fontKey" | "italic" | "color"> & {
     bg: z.ZodOptional<z.ZodString>;
-    variant: z.ZodOptional<z.ZodEnum<["solid", "soft", "outline"]>>;
 }, "strict", z.ZodTypeAny, {
-    variant?: "solid" | "soft" | "outline" | undefined;
+    weight?: "bold" | "normal" | undefined;
+    fontKey?: string | undefined;
+    italic?: boolean | undefined;
+    color?: string | undefined;
     bg?: string | undefined;
 }, {
-    variant?: "solid" | "soft" | "outline" | undefined;
+    weight?: "bold" | "normal" | undefined;
+    fontKey?: string | undefined;
+    italic?: boolean | undefined;
+    color?: string | undefined;
     bg?: string | undefined;
 }>;
+/**
+ * Which style vocabulary each kind accepts — TOTAL over the kind vocabulary
+ * since the any-text wave, so "unknown kind" can only mean an id this
+ * schema's vintage cannot dispatch (already refused by `objectKindOf`).
+ *
+ * EXPORTED for the web toolbar: `toolbarControlsFor` derives its control
+ * matrix from these shapes instead of hand-mirroring them, so a vocabulary
+ * change here reshapes the UI by construction.
+ */
+declare const STYLE_SCHEMA_FOR_KIND: Record<ProfileObjectKind, z.ZodObject<z.ZodRawShape>>;
 declare const profileLayoutSchema: z.ZodEffects<z.ZodObject<{
     v: z.ZodLiteral<1>;
     sectionOrder: z.ZodOptional<z.ZodArray<z.ZodEnum<["identity", "bio", "contact", "social", "actions", "cta", "footer"]>, "many">>;
@@ -22665,4 +22723,4 @@ declare function validatePhysicalConfig(data: unknown): ValidationResult<z.infer
 declare function validateDigitalConfig(data: unknown): ValidationResult<z.infer<typeof digitalConfigSchema>>;
 declare function validateConfiguration(data: unknown): ValidationResult<z.infer<typeof configurationCreateSchema>>;
 
-export { ADVANCE_FALLBACK_EM, CARD_H_MM, CARD_W_MM, CHIP_RADIUS_MM, CHIP_SCALE_FLOOR, type ChipAxis, EDGE_MARGIN_MM, EMPTY_TEXT_FLOOR_EM, ITALIC_OVERHANG_EM, MAX_CTA_BUTTONS, MIN_WALL_MM, NFC_COIL_DIAMETER_MM, NFC_RADIAL_CLEARANCE_MM, type PrintabilityCtx, type Pt, QR_MATRIX_CELLS, QR_MIN_SIZE_MM, QR_MODULE_MIN_MM, TEXT_LINE_FACTOR_EM, TEXT_MIN_EM_MM, type ValidationResult, type Violation, adminCardCreateSchema, bookingSchema, buttonObjectStyleSchema, cardAssetSchema, cardDesignMaterialSchema, cardDesignPatternSchema, cardDesignSchema, cardElementSchema, cardElementsSchema, cardProfileUpdateSchema, cardUpdateSchema, chipAnchorToMm, chipPlacementMaxXY, comboIdSchema, configurationCreateSchema, configurationUpdateSchema, contactDetailTogglesSchema, contactExchangeSchema, cornersOnCard, createOrderSchema, ctaButtonSchema, ctaButtonsSchema, digitalConfigSchema, digitalVisibilitySchema, elementPrintability, elementTransformSchema, entrySourceSchema, footprintOf, hubConfigSchema, hubProfilesUpdateSchema, imageObjectStyleSchema, isFiniteTransform, materialSchema, mmToNearestChipAnchor, obbCorners, patternFamilySchema, physicalConfigSchema, physicalContentOverridesSchema, profileAccessTokenCreateSchema, profileBackgroundSchema, profileCreateSchema, profileLayoutSchema, profilePinVerifySchema, profileUpdateSchema, profileUserDataSchema, profileVisibilitySchema, qrModeSchema, safeProfileLayout, sanitizeHttpUrl, sanitizeText, signupWithProfileSchema, socialLinksSchema, socialOverridesSchema, textAdvanceEm, textObjectStyleSchema, tipJarSchema, userDataSchema, validateConfiguration, validateDigitalConfig, validatePhysicalConfig, validateUserData, webAddressSchema };
+export { ADVANCE_FALLBACK_EM, CARD_H_MM, CARD_W_MM, CHIP_RADIUS_MM, CHIP_SCALE_FLOOR, type ChipAxis, EDGE_MARGIN_MM, EMPTY_TEXT_FLOOR_EM, ITALIC_OVERHANG_EM, MAX_CTA_BUTTONS, MIN_WALL_MM, NFC_COIL_DIAMETER_MM, NFC_RADIAL_CLEARANCE_MM, type PrintabilityCtx, type Pt, QR_MATRIX_CELLS, QR_MIN_SIZE_MM, QR_MODULE_MIN_MM, STYLE_SCHEMA_FOR_KIND, TEXT_LINE_FACTOR_EM, TEXT_MIN_EM_MM, type ValidationResult, type Violation, adminCardCreateSchema, bookingSchema, buttonObjectStyleSchema, cardAssetSchema, cardDesignMaterialSchema, cardDesignPatternSchema, cardDesignSchema, cardElementSchema, cardElementsSchema, cardProfileUpdateSchema, cardUpdateSchema, chipAnchorToMm, chipPlacementMaxXY, comboIdSchema, configurationCreateSchema, configurationUpdateSchema, contactDetailTogglesSchema, contactExchangeSchema, cornersOnCard, createOrderSchema, ctaButtonSchema, ctaButtonsSchema, digitalConfigSchema, digitalVisibilitySchema, elementPrintability, elementTransformSchema, entrySourceSchema, footprintOf, hubConfigSchema, hubProfilesUpdateSchema, imageObjectStyleSchema, isFiniteTransform, materialSchema, mmToNearestChipAnchor, obbCorners, patternFamilySchema, physicalConfigSchema, physicalContentOverridesSchema, profileAccessTokenCreateSchema, profileBackgroundSchema, profileCreateSchema, profileLayoutSchema, profilePinVerifySchema, profileUpdateSchema, profileUserDataSchema, profileVisibilitySchema, qrModeSchema, rowTextStyleSchema, safeProfileLayout, sanitizeHttpUrl, sanitizeText, signupWithProfileSchema, socialLinksSchema, socialOverridesSchema, textAdvanceEm, textObjectStyleSchema, tipJarSchema, userDataSchema, validateConfiguration, validateDigitalConfig, validatePhysicalConfig, validateUserData, webAddressSchema };

package/dist/index.js

@@ -484,13 +484,16 @@ var imageObjectStyleSchema = z.object({
   borderPx: z.number().int().min(0).max(8).optional(),
   shape: z.enum(["circle", "rounded", "square"]).optional()
 }).strict();
-var buttonObjectStyleSchema = z.object({
-  bg: z.string().regex(HEX_RE).optional(),
-  variant: z.enum(["solid", "soft", "outline"]).optional()
-}).strict();
+var rowTextStyleSchema = textObjectStyleSchema.omit({
+  align: true,
+  sizeStep: true
+});
+var buttonObjectStyleSchema = textObjectStyleSchema.pick({ color: true, weight: true, italic: true, fontKey: true }).extend({ bg: z.string().regex(HEX_RE).optional() }).strict();
 var STYLE_SCHEMA_FOR_KIND = {
   text: textObjectStyleSchema,
   freeText: textObjectStyleSchema,
+  contactRow: rowTextStyleSchema,
+  socialLink: rowTextStyleSchema,
   image: imageObjectStyleSchema,
   ctaButton: buttonObjectStyleSchema,
   linkOut: buttonObjectStyleSchema,
@@ -562,7 +565,7 @@ var profileLayoutSchema = z.object({
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
           path: ["objects", key, "style"],
-          message: `kind '${kind}' is not stylable`
+          message: `kind '${kind}' has no style vocabulary in this build`
         });
         continue;
       }
@@ -1186,6 +1189,7 @@ export {
   QR_MATRIX_CELLS,
   QR_MIN_SIZE_MM,
   QR_MODULE_MIN_MM,
+  STYLE_SCHEMA_FOR_KIND,
   TEXT_LINE_FACTOR_EM,
   TEXT_MIN_EM_MM,
   adminCardCreateSchema,
@@ -1235,6 +1239,7 @@ export {
   profileUserDataSchema,
   profileVisibilitySchema,
   qrModeSchema,
+  rowTextStyleSchema,
   safeProfileLayout,
   sanitizeHttpUrl,
   sanitizeText,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nfcard/validation",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Shared Zod validation schemas for the NFCard product family.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
   ],
   "dependencies": {
     "zod": "^3.24.0",
-    "@nfcard/types": "0.18.0"
+    "@nfcard/types": "0.19.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0"

package/src/profileLayout.test.ts

@@ -7,9 +7,9 @@
  * strings spelled out.
  */
 import { describe, expect, it } from 'vitest'
-import { CANONICAL_OBJECT_ORDER, ctaObjectIndex, type ProfileLayout } from '@nfcard/types'
+import { CANONICAL_OBJECT_ORDER, PROFILE_OBJECT_KINDS, ctaObjectIndex, type ProfileLayout } from '@nfcard/types'
 import { MAX_CTA_BUTTONS, digitalConfigSchema } from './index'
-import { profileLayoutSchema, safeProfileLayout } from './profileLayout'
+import { STYLE_SCHEMA_FOR_KIND, profileLayoutSchema, safeProfileLayout } from './profileLayout'
 
 const okLayout: ProfileLayout = {
   v: 1,
@@ -21,8 +21,8 @@ const okLayout: ProfileLayout = {
   objects: {
     name: { style: { color: '#112233', sizeStep: 'lg', weight: 'bold' } },
     avatar: { style: { crop: { x: 0.5, y: 0.25, zoom: 1.6 }, borderColor: '#ffffff', borderPx: 3 } },
-    'cta-0': { style: { bg: '#16a34a', variant: 'solid' } },
-    booking: { style: { variant: 'outline' } },
+    'cta-0': { style: { bg: '#16a34a', color: '#ffffff' } },
+    booking: { style: { weight: 'bold' } },
   },
   ownedObjects: [{ id: 'ft-abcd', kind: 'freeText', section: 'bio', text: 'Hello there' }],
 }
@@ -69,10 +69,10 @@ describe('profileLayoutSchema — rejects abuse', () => {
     expect(bad({ v: 1, objectOrder: { unknownSection: ['social-x'] } })).toBe(false)
   })
 
-  it('objects: unknown ids, non-stylable kinds, injection-shaped values', () => {
+  it('objects: unknown ids, off-vocabulary props, injection-shaped values', () => {
     expect(bad({ v: 1, objects: { 'not-a-thing': { style: {} } } })).toBe(false)
-    // contactRow is arrangeable but not stylable in v1 — storing a style the
-    // render never reads is the defect, not a feature.
+    // contactRow is TEXT-stylable since the any-text wave, but `bg` never
+    // joined its vocabulary — a row has no fill of its own.
     expect(bad({ v: 1, objects: { 'contact-email': { style: { bg: '#112233' } } } })).toBe(false)
     expect(bad({ v: 1, objects: { name: { style: { color: 'red;}{' } } } })).toBe(false)
     expect(bad({ v: 1, objects: { name: { style: { color: '#12345' } } } })).toBe(false)
@@ -116,6 +116,107 @@ describe('profileLayoutSchema — rejects abuse', () => {
   })
 })
 
+describe('the any-text wave: per-kind style vocabulary (kind × prop matrix)', () => {
+  const style = (id: string, s: Record<string, unknown>) =>
+    profileLayoutSchema.safeParse({ v: 1, objects: { [id]: { style: s } } }).success
+
+  it('rows (contactRow / socialLink) take the text vocabulary minus align/sizeStep', () => {
+    const full = {
+      color: '#112233',
+      weight: 'bold',
+      italic: true,
+      underline: true,
+      fontKey: 'inter',
+    }
+    expect(style('contact-email', full)).toBe(true)
+    expect(style('social-instagram', full)).toBe(true)
+    // Row alignment is the template's grid — align stays refused. And a row
+    // is a compound (label/value spans with own px sizes), so sizeStep has
+    // nothing honest to render — refused rather than stored dead.
+    expect(style('contact-email', { align: 'center' })).toBe(false)
+    expect(style('social-instagram', { align: 'start' })).toBe(false)
+    expect(style('contact-email', { sizeStep: 'sm' })).toBe(false)
+    expect(style('social-instagram', { sizeStep: 'lg' })).toBe(false)
+  })
+
+  it('buttons take label styling; geometry props stay out', () => {
+    const label = { color: '#112233', weight: 'bold', italic: true, fontKey: 'inter' }
+    expect(style('cta-0', { ...label, bg: '#16a34a' })).toBe(true)
+    expect(style('booking', { ...label, bg: '#16a34a' })).toBe(true)
+    // No sizeStep (button geometry is the template's), no underline, no align.
+    expect(style('cta-0', { sizeStep: 'lg' })).toBe(false)
+    expect(style('cta-0', { underline: true })).toBe(false)
+    expect(style('booking', { align: 'center' })).toBe(false)
+  })
+
+  it('🔴 variant is GONE for every button kind — no surface could ever write it', () => {
+    expect(style('act-share', { color: '#112233', bg: '#16a34a', weight: 'bold' })).toBe(true)
+    for (const id of ['cta-0', 'booking', 'act-share']) {
+      expect(style(id, { variant: 'solid' })).toBe(false)
+    }
+  })
+
+  it('🔴 the vocabulary is TOTAL: every kind dispatches to a schema', () => {
+    // Driven off PROFILE_OBJECT_KINDS, not a hardcoded list — a NINTH kind
+    // added to types without a row here fails THIS line, not a production
+    // render. (tsc would catch it too, but tsc does not run on the publish
+    // path — validation 0.24.0 shipped while tsc was red.)
+    for (const kind of PROFILE_OBJECT_KINDS) {
+      expect(STYLE_SCHEMA_FOR_KIND[kind], `no style schema for kind '${kind}'`).toBeDefined()
+    }
+    // And through the real dispatch: one id per kind; `{}` is the least
+    // style. (The empty-style accept is also the additive guarantee: old
+    // documents keep parsing as vocabularies widen.)
+    const representative: Record<string, string> = {
+      text: 'name',
+      freeText: 'ft-abcd',
+      contactRow: 'contact-email',
+      socialLink: 'social-instagram',
+      image: 'avatar',
+      ctaButton: 'cta-0',
+      linkOut: 'booking',
+      action: 'act-share',
+    }
+    for (const kind of PROFILE_OBJECT_KINDS) {
+      const id = representative[kind]
+      expect(id, `no representative id for kind '${kind}' — extend this test`).toBeDefined()
+      expect(style(id, {})).toBe(true)
+    }
+  })
+
+  it('🔴 a kind the table misses is a REFUSAL, never a throw', () => {
+    // The cross-package skew case: a types vintage that knows a kind this
+    // validation build does not. The guard must add an issue — an exception
+    // in superRefine ESCAPES safeParse (zod 3.25), and safeProfileLayout's
+    // "the public page never 500s over decoration" contract dies with it.
+    const stolen = STYLE_SCHEMA_FOR_KIND.action
+    delete (STYLE_SCHEMA_FOR_KIND as Partial<typeof STYLE_SCHEMA_FOR_KIND>).action
+    try {
+      const r = profileLayoutSchema.safeParse({
+        v: 1,
+        objects: { 'act-share': { style: { weight: 'bold' } } },
+      })
+      expect(r.success).toBe(false)
+      // A style-LESS override on the unknown kind keeps the old accept.
+      expect(
+        profileLayoutSchema.safeParse({ v: 1, objects: { 'act-share': {} } }).success,
+      ).toBe(true)
+    } finally {
+      STYLE_SCHEMA_FOR_KIND.action = stolen
+    }
+  })
+
+  it('the distinct-font cap counts row and button fontKeys too', () => {
+    const fonts = Object.fromEntries(
+      ['name', 'contact-email', 'social-instagram', 'cta-0', 'booking'].map((id, i) => [
+        id,
+        { style: { fontKey: `font-${i}` } },
+      ]),
+    )
+    expect(profileLayoutSchema.safeParse({ v: 1, objects: fonts }).success).toBe(false)
+  })
+})
+
 describe('digitalConfigSchema integration', () => {
   const baseConfig = {
     templateId: 'classic',

package/src/profileLayout.ts

@@ -83,22 +83,47 @@ export const imageObjectStyleSchema = z
   })
   .strict()
 
-export const buttonObjectStyleSchema = z
-  .object({
-    bg: z.string().regex(HEX_RE).optional(),
-    variant: z.enum(['solid', 'soft', 'outline']).optional(),
-  })
+/**
+ * Contact rows and social chips: text minus `align` and `sizeStep`. Row
+ * alignment is the template's grid; and a row is a COMPOUND (label/value
+ * spans with their own px sizes), so no wrapper-level em can scale it
+ * without destroying the internal hierarchy — either would be a
+ * stored-but-dead field.
+ */
+export const rowTextStyleSchema = textObjectStyleSchema.omit({
+  align: true,
+  sizeStep: true,
+})
+
+/** Label styling (the text vocabulary's `color`/`weight`/`italic`/`fontKey`,
+ *  DERIVED so the validators stay in lockstep) + `bg` fill. No `sizeStep`
+ *  in v1 — button geometry is the template's. `variant` is GONE (0.24.0
+ *  accepted it and the render did style it): NO SURFACE COULD EVER WRITE IT
+ *  — the toolbar exposes no variant control and none is planned — and a
+ *  stored-but-unwritable field is dead weight on every future vintage. No
+ *  deployed tag ever accepted one, so nothing stored carries it. */
+export const buttonObjectStyleSchema = textObjectStyleSchema
+  .pick({ color: true, weight: true, italic: true, fontKey: true })
+  .extend({ bg: z.string().regex(HEX_RE).optional() })
   .strict()
 
 /**
- * Which style vocabulary each kind accepts. `contactRow` and `socialLink`
- * are deliberately ABSENT in v1: no template renders a style for them yet,
- * and a schema that stores what the server never reads is the EditTextSheet
- * lesson in write form. Additive to extend.
+ * Which style vocabulary each kind accepts — TOTAL over the kind vocabulary
+ * since the any-text wave, so "unknown kind" can only mean an id this
+ * schema's vintage cannot dispatch (already refused by `objectKindOf`).
+ *
+ * EXPORTED for the web toolbar: `toolbarControlsFor` derives its control
+ * matrix from these shapes instead of hand-mirroring them, so a vocabulary
+ * change here reshapes the UI by construction.
  */
-const STYLE_SCHEMA_FOR_KIND: Partial<Record<ProfileObjectKind, z.ZodTypeAny>> = {
+export const STYLE_SCHEMA_FOR_KIND: Record<
+  ProfileObjectKind,
+  z.ZodObject<z.ZodRawShape>
+> = {
   text: textObjectStyleSchema,
   freeText: textObjectStyleSchema,
+  contactRow: rowTextStyleSchema,
+  socialLink: rowTextStyleSchema,
   image: imageObjectStyleSchema,
   ctaButton: buttonObjectStyleSchema,
   linkOut: buttonObjectStyleSchema,
@@ -191,11 +216,18 @@ export const profileLayoutSchema = z
         }
         const style = overrideParsed.data.style
         if (style === undefined) continue
+        // The table is TOTAL by type, but tsc does not run on the publish
+        // path and `objectKindOf` lives in @nfcard/types behind a ^range —
+        // a types vintage that knows a NINTH kind can resolve under a
+        // validation build whose table stops at eight. Without this guard
+        // that skew is a TypeError that ESCAPES safeParse (verified against
+        // zod 3.25), turning `safeProfileLayout`'s promised null into a 500
+        // on the public render. Refusal, never a throw.
         if (!styleSchema) {
           ctx.addIssue({
             code: z.ZodIssueCode.custom,
             path: ['objects', key, 'style'],
-            message: `kind '${kind}' is not stylable`,
+            message: `kind '${kind}' has no style vocabulary in this build`,
           })
           continue
         }