@tamagui/style-grammar 0.0.0-bootstrap.0 → 3.0.0-beta.643.1

package/src/valueParser.ts

@@ -0,0 +1,193 @@
+// The universal flat value parser.
+//
+//   value  := base? clause*
+//   clause := modifier (":" modifier)* ":" payload
+//
+// See plans/dom-tailwind-flat-values.md — "The universal value grammar". The
+// parser only splits: `base` and every `payload` come back as trimmed raw CSS
+// component-value sequences with no interpretation and no token resolution.
+//
+// The split itself is `scanFlatValue`, the one lexer every implementation of
+// this grammar drives; this file is what that split MEANS, which is the part
+// the registry decides. Read `scanFlatValue.ts` for why a top-level colon,
+// brace or semicolon is structural and everything inside a string or a paren is
+// not.
+
+import {
+  scanFlatValue,
+  type FlatScanErrorCode,
+  type FlatValueVisitor,
+} from './scanFlatValue'
+import type {
+  ModifierRegistryView,
+  ParsedClause,
+  ValueParseError,
+  ValueParseErrorCode,
+  ValueParseResult,
+} from './valueTypes'
+
+const CHAR_COLON = 58
+
+const noClauses: readonly ParsedClause[] = Object.freeze([])
+
+export interface ValueSourceSpan {
+  kind: 'base' | 'payload' | 'modifier' | 'word'
+  start: number
+  end: number
+}
+
+export interface ValueParseWithSourceSpans {
+  result: ValueParseResult
+  spans: readonly ValueSourceSpan[]
+}
+
+/**
+ * NOT A SAFETY CHECK. A successful parse says the value is well-formed FLAT
+ * VALUE SYNTAX. It does not say the value is safe to interpolate into CSS.
+ *
+ * `scanFlatValue` tracks the same constructs CSS's tokenizer does (comments,
+ * strings that a newline ends, `url()`, paren nesting), so a value whose
+ * delimiters do not actually close is an error rather than silently trusted.
+ * That covers the constructs a value can leave OPEN; it is not an injection
+ * guard. `emitValue` and `getStyleObject` used to call a
+ * `carriesTopLevelInjection` guard independently; it was removed by owner
+ * decision, on the grounds that a style value is authored rather than user
+ * input, and the web lowering emits payloads verbatim by contract.
+ *
+ * So the rule lives upstream of this file: never put a user-controlled string
+ * in a style value. A payload carrying `;}` closes its own rule and everything
+ * after it is a selector block the author never wrote. Do not gate emission on
+ * `parseValue(...).ok` either; it answers a syntax question, not a safety one.
+ */
+export function parseValue(
+  input: string,
+  registry: ModifierRegistryView
+): ValueParseResult {
+  return parseValueInternal(input, registry)
+}
+
+/**
+ * Parses through the runtime scanner while also retaining source boundaries for
+ * editor tooling. The ordinary runtime path does not allocate these spans.
+ */
+export function parseValueWithSourceSpans(
+  input: string,
+  registry: ModifierRegistryView
+): ValueParseWithSourceSpans {
+  const spans: ValueSourceSpan[] = []
+  return {
+    result: parseValueInternal(input, registry, spans),
+    spans,
+  }
+}
+
+function scanErrorMessage(code: FlatScanErrorCode, input: string, index: number): string {
+  if (code === 'invalid-character') {
+    return `"${input[index]}" cannot appear in a value: it would end the declaration or rule`
+  }
+  if (code === 'unterminated-string') {
+    return `unterminated ${input[index]} string`
+  }
+  if (code === 'unterminated-comment') {
+    return 'unterminated "/*" comment: it would swallow the rules after this one'
+  }
+  if (code === 'stray-comment-close') {
+    return 'stray "*/": it would close a comment opened somewhere else'
+  }
+  return 'unterminated "(" in value'
+}
+
+function parseValueInternal(
+  input: string,
+  registry: ModifierRegistryView,
+  sourceSpans?: ValueSourceSpan[]
+): ValueParseResult {
+  let errors: ValueParseError[] | null = null
+  let base: string | null = null
+  let clauses: ParsedClause[] | null = null
+  // modifiers of the clause whose payload is currently being collected
+  let pending: string[] | null = null
+  // where the base, or the current payload, starts before trimming, which is
+  // what an empty payload has to point its diagnostic at
+  let segmentStart = 0
+
+  const addError = (
+    code: ValueParseErrorCode,
+    index: number,
+    message: string,
+    modifier?: string
+  ): void => {
+    ;(errors ||= []).push(
+      modifier === undefined
+        ? { code, index, message }
+        : { code, index, message, modifier }
+    )
+  }
+
+  const visitor: FlatValueVisitor = {
+    segment(start, end, isBase) {
+      sourceSpans?.push({ kind: isBase ? 'base' : 'payload', start, end })
+      if (isBase) {
+        base = start < end ? input.slice(start, end) : null
+        return
+      }
+      if (start >= end) {
+        addError(
+          'empty-payload',
+          segmentStart,
+          `the "${pending!.join(':')}:" clause has no value`
+        )
+        return
+      }
+      ;(clauses ||= []).push({ modifiers: pending!, payload: input.slice(start, end) })
+    },
+
+    // a clause word ended: everything before its last top-level colon is the
+    // modifier chain, everything after it begins the payload
+    chain(chainStart, chainEnd) {
+      const modifiers: string[] = []
+      let nameStart = chainStart
+      for (let index = chainStart; index <= chainEnd; index++) {
+        if (index !== chainEnd && input.charCodeAt(index) !== CHAR_COLON) continue
+        if (index === nameStart) {
+          addError('empty-modifier', index, 'a modifier chain has an empty segment')
+        } else {
+          const name = input.slice(nameStart, index)
+          sourceSpans?.push({ kind: 'modifier', start: nameStart, end: index })
+          if (registry.get(name) === undefined) {
+            addError(
+              'unregistered-modifier',
+              nameStart,
+              `"${name}" is not a registered modifier`,
+              name
+            )
+          }
+          modifiers.push(name)
+        }
+        nameStart = index + 1
+      }
+      pending = modifiers
+      segmentStart = chainEnd + 1
+      return true
+    },
+
+    error(code, index) {
+      addError(code, index, scanErrorMessage(code, input, index))
+    },
+  }
+
+  if (sourceSpans) {
+    // only the trailing bare word is a completion position the spans have no
+    // other name for: every earlier word is inside a base or a payload span
+    visitor.word = (start, end, isChain) => {
+      if (!isChain && end === input.length) {
+        sourceSpans.push({ kind: 'word', start, end })
+      }
+    }
+  }
+
+  scanFlatValue(input, visitor)
+
+  if (errors !== null) return { ok: false, errors }
+  return { ok: true, value: { base, clauses: clauses ?? noClauses } }
+}

package/src/valueTypes.ts

@@ -0,0 +1,136 @@
+// The shared IR for the universal flat value grammar.
+//
+// This file is the contract between the value parser, the per-longhand program
+// merge engine, the compiler, and every frontend (props, Tailwind classes,
+// styled skins). See plans/dom-tailwind-flat-values.md on main — "The universal
+// value grammar" and "Programs and merging" — for the full design. The rules
+// that matter are restated here so this file can be read standalone.
+//
+// Grammar:
+//
+//   value  := base? clause*
+//   clause := modifier (":" modifier)* ":" payload
+//
+// - `base` and each `payload` are plain CSS component-value sequences. They are
+//   NOT interpreted here; the parser only splits, it never resolves.
+// - Clause detection is purely syntactic: a top-level colon (outside strings
+//   and outside any paren nesting, url() included) always starts a clause. A
+//   top-level colon is never valid inside a CSS component value, so this is
+//   unambiguous with zero configuration.
+// - The identifier chain before the colon must be entirely registered
+//   modifiers. An unregistered modifier is a hard parse error (`hver:` never
+//   silently becomes part of a value).
+// - An empty payload is a parse error. A clause with no preceding base is fine
+//   (`bg="hover:red"`).
+//
+// Programs:
+//
+// - Every authored prop expands (via shorthand + family tables) to one or more
+//   CSS longhands. Each longhand accumulates one program in authored order.
+//   Contributions merge by base or normalized condition-set slot, so a later
+//   clause replaces only that slot and unrelated earlier clauses persist.
+
+export type ModifierKind =
+  | 'state'
+  | 'theme'
+  | 'media'
+  | 'platform'
+  | 'group'
+  /** container queries: `@sm:` nearest container, `@sm/card:` named */
+  | 'container'
+
+/** Maximum distinct non-platform conditions one emitted clause can encode. */
+export const grammarMaxNonPlatformDepth = 5
+
+/**
+ * What the parser needs to know about registered modifiers. Implementations
+ * project the user config (media keys, root themes, platform names) plus the
+ * built-in state vocabulary into this view. Parameterized modifiers
+ * (`group-<name>-<state>`) are the implementation's concern — `get` receives
+ * the full authored spelling.
+ */
+export interface ModifierRegistryView {
+  get(name: string): ModifierKind | undefined
+  /**
+   * Config-derived modifier trie lookup for authoring one canonical chain.
+   * Implementations that only parse values may omit it; tooling refuses to
+   * invent a completion vocabulary when it is absent.
+   */
+  next?(modifiers: readonly string[]): readonly string[]
+}
+
+/** one `modifiers ":" payload` clause, modifiers in authored order */
+export interface ParsedClause {
+  modifiers: readonly string[]
+  /** trimmed raw CSS component-value sequence; never empty */
+  payload: string
+}
+
+export interface ParsedValue {
+  /** trimmed unconditional leading value, or null when the string starts with a clause */
+  base: string | null
+  clauses: readonly ParsedClause[]
+}
+
+export type ValueParseErrorCode =
+  | 'unregistered-modifier'
+  | 'empty-payload'
+  | 'empty-modifier'
+  | 'unterminated-string'
+  | 'unterminated-function'
+  /**
+   * an opened comment that never closes. `getAllRules()` joins rules into one
+   * blob for SSR, so an open comment blanks the rules after it until some later
+   * close delimiter turns them back on
+   */
+  | 'unterminated-comment'
+  /** a close delimiter with nothing open, which closes another rule's comment */
+  | 'stray-comment-close'
+  /**
+   * a top-level `{`, `}`, or `;` — never valid in a CSS component value, and
+   * rejecting them here is what makes rule/selector injection through a
+   * payload structurally impossible in the web lowering
+   */
+  | 'invalid-character'
+
+export interface ValueParseError {
+  code: ValueParseErrorCode
+  /** character offset into the source string where the error was detected */
+  index: number
+  message: string
+  /** the offending modifier spelling, for unregistered-modifier */
+  modifier?: string
+}
+
+export type ValueParseResult =
+  | { ok: true; value: ParsedValue }
+  | { ok: false; errors: readonly ValueParseError[] }
+
+/**
+ * CSS-wide keywords and universal values that resolve as literal CSS even when
+ * ident resolution is config-first. A token may never take one of these names;
+ * config creation must reject it. Shared by the parser's ident resolution and
+ * config-time validation.
+ */
+export const reservedCssIdents: ReadonlySet<string> = new Set([
+  'inherit',
+  'initial',
+  'unset',
+  'revert',
+  'none',
+  'auto',
+  'transparent',
+  'currentColor',
+])
+
+/**
+ * One longhand's merged program: which CSS longhand, the parsed value that owns
+ * it, and which authored prop contributed it (for diagnostics and devtools).
+ */
+export interface LonghandProgram {
+  /** camelCase longhand matching React Native / react style keys */
+  property: string
+  value: ParsedValue
+  /** the authored prop name that won this longhand */
+  sourceProp: string
+}

package/types/backgroundFamily.d.ts

@@ -0,0 +1,17 @@
+import type { ParsedValue } from "./valueTypes";
+export declare const namedCssColors: ReadonlySet<string>;
+export declare function splitTopLevelComponents(value: string): string[];
+export declare function classifyComponent(component: string, colorTokens: ReadonlySet<string>): "color" | "image" | null;
+export declare function splitBackgroundValue(value: ParsedValue, colorTokens: ReadonlySet<string>): {
+	entries: Array<{
+		property: "backgroundColor" | "backgroundImage";
+		value: ParsedValue;
+	}>;
+	errors: Array<{
+		code: "unsupported-bg-component";
+		component: string;
+		where: "base" | number;
+	}>;
+};
+
+//# sourceMappingURL=backgroundFamily.d.ts.map

package/types/backgroundFamily.d.ts.map

@@ -0,0 +1,11 @@
+{
+  "mappings": "AAAA,cAA4B,mBAAmB;AAE/C,OAAO,cAAM,gBAAgB;AAmB7B,OAAO,iBAAS,wBAAwB;AAiDxC,OAAO,iBAAS,kBACd,mBACA,aAAa,sBACZ,UAAU;AAyBb,OAAO,iBAAS,qBACd,OAAO,aACP,aAAa,sBACZ;CACD,SAAS,MAAM;EACb,UAAU,oBAAoB;EAC9B,OAAO;;CAET,QAAQ,MAAM;EACZ,MAAM;EACN;EACA,OAAO",
+  "names": [],
+  "sources": [
+    "src/backgroundFamily.ts"
+  ],
+  "version": 3,
+  "sourcesContent": [
+    "import type { ParsedClause, ParsedValue } from './valueTypes'\n\nexport const namedCssColors: ReadonlySet<string> = new Set(\n  'aliceblue antiquewhite aqua aquamarine azure beige bisque black blanchedalmond blue blueviolet brown burlywood cadetblue chartreuse chocolate coral cornflowerblue cornsilk crimson cyan darkblue darkcyan darkgoldenrod darkgray darkgreen darkgrey darkkhaki darkmagenta darkolivegreen darkorange darkorchid darkred darksalmon darkseagreen darkslateblue darkslategray darkslategrey darkturquoise darkviolet deeppink deepskyblue dimgray dimgrey dodgerblue firebrick floralwhite forestgreen fuchsia gainsboro ghostwhite gold goldenrod gray green greenyellow grey honeydew hotpink indianred indigo ivory khaki lavender lavenderblush lawngreen lemonchiffon lightblue lightcoral lightcyan lightgoldenrodyellow lightgray lightgreen lightgrey lightpink lightsalmon lightseagreen lightskyblue lightslategray lightslategrey lightsteelblue lightyellow lime limegreen linen magenta maroon mediumaquamarine mediumblue mediumorchid mediumpurple mediumseagreen mediumslateblue mediumspringgreen mediumturquoise mediumvioletred midnightblue mintcream mistyrose moccasin navajowhite navy oldlace olive olivedrab orange orangered orchid palegoldenrod palegreen paleturquoise palevioletred papayawhip peachpuff peru pink plum powderblue purple rebeccapurple red rosybrown royalblue saddlebrown salmon sandybrown seagreen seashell sienna silver skyblue slateblue slategray slategrey snow springgreen steelblue tan teal thistle tomato turquoise violet wheat white whitesmoke yellow yellowgreen'.split(\n    ' '\n  )\n)\n\nconst colorFunctions = new Set([\n  'rgb',\n  'rgba',\n  'hsl',\n  'hsla',\n  'hwb',\n  'lab',\n  'lch',\n  'oklab',\n  'oklch',\n  'color',\n])\n\nexport function splitTopLevelComponents(value: string): string[] {\n  const components: string[] = []\n  let current = ''\n  let depth = 0\n  let quote = ''\n  let escaped = false\n\n  for (let index = 0; index < value.length; index++) {\n    const char = value[index]\n    if (escaped) {\n      current += char\n      escaped = false\n      continue\n    }\n    if (char === '\\\\') {\n      current += char\n      escaped = true\n      continue\n    }\n    if (quote) {\n      current += char\n      if (char === quote) quote = ''\n      continue\n    }\n    if (char === '\"' || char === \"'\") {\n      current += char\n      quote = char\n      continue\n    }\n    if (char === '(') depth++\n    if (char === ')') depth--\n\n    const code = value.charCodeAt(index)\n    const whitespace =\n      code === 9 || code === 10 || code === 12 || code === 13 || code === 32\n    if (depth === 0 && whitespace) {\n      if (current) {\n        components.push(current)\n        current = ''\n      }\n    } else {\n      current += char\n    }\n  }\n\n  if (current) components.push(current)\n  return components\n}\n\nexport function classifyComponent(\n  component: string,\n  colorTokens: ReadonlySet<string>\n): 'color' | 'image' | null {\n  const functionMatch = /^([a-z][a-z0-9-]*)\\([\\s\\S]*\\)$/i.exec(component)\n  if (functionMatch) {\n    const name = functionMatch[1].toLowerCase()\n    if (name === 'url' || name === 'image-set' || name.endsWith('-gradient')) {\n      return 'image'\n    }\n    if (colorFunctions.has(name)) return 'color'\n  }\n\n  if (/^#[\\da-f]{3}(?:[\\da-f]{1}|[\\da-f]{3}(?:[\\da-f]{2})?)?$/i.test(component)) {\n    return 'color'\n  }\n\n  const tokenName = component.replace(/\\/\\d+$/, '')\n  if (colorTokens.has(tokenName)) return 'color'\n\n  const lower = component.toLowerCase()\n  if (lower === 'transparent' || lower === 'currentcolor' || namedCssColors.has(lower)) {\n    return 'color'\n  }\n\n  return null\n}\n\nexport function splitBackgroundValue(\n  value: ParsedValue,\n  colorTokens: ReadonlySet<string>\n): {\n  entries: Array<{\n    property: 'backgroundColor' | 'backgroundImage'\n    value: ParsedValue\n  }>\n  errors: Array<{\n    code: 'unsupported-bg-component'\n    component: string\n    where: 'base' | number\n  }>\n} {\n  const colorProgram: { base: string | null; clauses: ParsedClause[] } = {\n    base: null,\n    clauses: [],\n  }\n  const imageProgram: { base: string | null; clauses: ParsedClause[] } = {\n    base: null,\n    clauses: [],\n  }\n  const errors: Array<{\n    code: 'unsupported-bg-component'\n    component: string\n    where: 'base' | number\n  }> = []\n  let hasColor = false\n  let hasImage = false\n\n  for (let clauseIndex = -1; clauseIndex < value.clauses.length; clauseIndex++) {\n    const isBase = clauseIndex === -1\n    const payload = isBase ? value.base : value.clauses[clauseIndex].payload\n    if (payload === null) continue\n\n    let colorComponent: string | null = null\n    let imageComponent: string | null = null\n    const where = isBase ? 'base' : clauseIndex\n\n    for (const component of splitTopLevelComponents(payload)) {\n      const kind = classifyComponent(component, colorTokens)\n      if (kind === 'image' && imageComponent === null) {\n        imageComponent = component\n      } else if (kind === 'color' && colorComponent === null) {\n        colorComponent = component\n      } else {\n        errors.push({ code: 'unsupported-bg-component', component, where })\n      }\n    }\n\n    if (colorComponent !== null) {\n      hasColor = true\n      if (isBase) {\n        colorProgram.base = colorComponent\n      } else {\n        colorProgram.clauses.push({\n          modifiers: value.clauses[clauseIndex].modifiers,\n          payload: colorComponent,\n        })\n      }\n    }\n\n    if (imageComponent !== null) {\n      hasImage = true\n      if (isBase) {\n        imageProgram.base = imageComponent\n      } else {\n        imageProgram.clauses.push({\n          modifiers: value.clauses[clauseIndex].modifiers,\n          payload: imageComponent,\n        })\n      }\n    }\n  }\n\n  const entries: Array<{\n    property: 'backgroundColor' | 'backgroundImage'\n    value: ParsedValue\n  }> = []\n  if (hasColor) entries.push({ property: 'backgroundColor', value: colorProgram })\n  if (hasImage) entries.push({ property: 'backgroundImage', value: imageProgram })\n\n  return { entries, errors }\n}\n"
+  ]
+}

package/types/borderFamily.d.ts

@@ -0,0 +1,23 @@
+import type { ParsedValue } from "./valueTypes";
+interface BorderFamilyTargets {
+	width: readonly string[];
+	style: readonly string[];
+	color: readonly string[];
+}
+/** authored prop -> the true longhands each component kind lands on */
+export declare const borderFamilyTargets: Readonly<Record<string, BorderFamilyTargets>>;
+export interface BorderFamilyError {
+	code: "unsupported-border-component";
+	component: string;
+	where: "base" | number;
+}
+export declare function splitBorderValue(property: string, value: ParsedValue, colorTokens: ReadonlySet<string>): {
+	entries: Array<{
+		property: string;
+		value: ParsedValue;
+	}>;
+	errors: BorderFamilyError[];
+};
+export {};
+
+//# sourceMappingURL=borderFamily.d.ts.map

package/types/borderFamily.d.ts.map

@@ -0,0 +1,11 @@
+{
+  "mappings": "AASA,cAA4B,mBAAmB;UAErC,oBAAoB;CAC5B;CACA;CACA;;;AAMF,OAAO,cAAM,qBAAqB,SAAS,eAAe;AAuE1D,iBAAiB,kBAAkB;CACjC,MAAM;CACN;CACA,OAAO;;AAST,OAAO,iBAAS,iBACd,kBACA,OAAO,aACP,aAAa,sBACZ;CACD,SAAS,MAAM;EAAE;EAAkB,OAAO;;CAC1C,QAAQ",
+  "names": [],
+  "sources": [
+    "src/borderFamily.ts"
+  ],
+  "version": 3,
+  "sourcesContent": [
+    "// The border family: value-dependent splitting of the resetting CSS border\n// shorthands into per-longhand programs, the background family's model applied\n// to width/style/color. A program must never sit on a resetting shorthand —\n// the order-free cross-program encoding depends on every program owning one\n// true longhand — so `border=\"2px solid red hover:blue\"` becomes width, style,\n// and color programs per side, and a later `borderColor` restates exactly the\n// color longhands.\n\nimport { classifyComponent, splitTopLevelComponents } from './backgroundFamily'\nimport type { ParsedClause, ParsedValue } from './valueTypes'\n\ninterface BorderFamilyTargets {\n  width: readonly string[]\n  style: readonly string[]\n  color: readonly string[]\n}\n\nconst sides = ['Top', 'Right', 'Bottom', 'Left'] as const\n\n/** authored prop -> the true longhands each component kind lands on */\nexport const borderFamilyTargets: Readonly<Record<string, BorderFamilyTargets>> = {\n  border: {\n    width: sides.map((side) => `border${side}Width`),\n    style: sides.map((side) => `border${side}Style`),\n    color: sides.map((side) => `border${side}Color`),\n  },\n  ...Object.fromEntries(\n    sides.map((side) => [\n      `border${side}`,\n      {\n        width: [`border${side}Width`],\n        style: [`border${side}Style`],\n        color: [`border${side}Color`],\n      },\n    ])\n  ),\n  outline: {\n    width: ['outlineWidth'],\n    style: ['outlineStyle'],\n    color: ['outlineColor'],\n  },\n  // logical shorthands split into CSS logical longhands. web lowers them\n  // verbatim; RN has no logical block/inline border properties, so native\n  // evaluation diagnoses and drops these longhands (no silent physical\n  // approximation — the mapping depends on writing mode)\n  borderBlock: {\n    width: ['borderBlockStartWidth', 'borderBlockEndWidth'],\n    style: ['borderBlockStartStyle', 'borderBlockEndStyle'],\n    color: ['borderBlockStartColor', 'borderBlockEndColor'],\n  },\n  borderInline: {\n    width: ['borderInlineStartWidth', 'borderInlineEndWidth'],\n    style: ['borderInlineStartStyle', 'borderInlineEndStyle'],\n    color: ['borderInlineStartColor', 'borderInlineEndColor'],\n  },\n}\n\nconst lineStyles = new Set([\n  'none',\n  'hidden',\n  'dotted',\n  'dashed',\n  'solid',\n  'double',\n  'groove',\n  'ridge',\n  'inset',\n  'outset',\n])\n\nconst widthKeywords = new Set(['thin', 'medium', 'thick'])\n\n// a length: bare number (RN spelling), number+unit, or a width keyword.\n// calc() and var() also measure as widths when nothing else claims them\nconst lengthPattern = /^-?(\\d+\\.?\\d*|\\.\\d+)([a-z%]+)?$/i\n\nfunction classifyBorderComponent(\n  component: string,\n  property: string,\n  colorTokens: ReadonlySet<string>\n): 'width' | 'style' | 'color' | null {\n  const lower = component.toLowerCase()\n  if (lineStyles.has(lower)) return 'style'\n  // outline-style additionally allows auto\n  if (lower === 'auto' && property === 'outline') return 'style'\n  if (widthKeywords.has(lower) || lengthPattern.test(component)) return 'width'\n  if (classifyComponent(component, colorTokens) === 'color') return 'color'\n  if (/^(calc|var|min|max|clamp)\\(/i.test(component)) return 'width'\n  return null\n}\n\nexport interface BorderFamilyError {\n  code: 'unsupported-border-component'\n  component: string\n  where: 'base' | number\n}\n\ninterface MutableProgram {\n  base: string | null\n  clauses: ParsedClause[]\n  present: boolean\n}\n\nexport function splitBorderValue(\n  property: string,\n  value: ParsedValue,\n  colorTokens: ReadonlySet<string>\n): {\n  entries: Array<{ property: string; value: ParsedValue }>\n  errors: BorderFamilyError[]\n} {\n  const targets = borderFamilyTargets[property]\n  const errors: BorderFamilyError[] = []\n  const kinds = ['width', 'style', 'color'] as const\n  const programs: Record<(typeof kinds)[number], MutableProgram> = {\n    width: { base: null, clauses: [], present: false },\n    style: { base: null, clauses: [], present: false },\n    color: { base: null, clauses: [], present: false },\n  }\n\n  for (let clauseIndex = -1; clauseIndex < value.clauses.length; clauseIndex++) {\n    const isBase = clauseIndex === -1\n    const payload = isBase ? value.base : value.clauses[clauseIndex].payload\n    if (payload === null) continue\n    const where = isBase ? ('base' as const) : clauseIndex\n\n    const found: Partial<Record<(typeof kinds)[number], string>> = {}\n    for (const component of splitTopLevelComponents(payload)) {\n      const kind = classifyBorderComponent(component, property, colorTokens)\n      if (kind === null || found[kind] !== undefined) {\n        errors.push({ code: 'unsupported-border-component', component, where })\n        continue\n      }\n      found[kind] = component\n    }\n\n    // Carry the shorthand's effective zero width explicitly. Web receives an\n    // equivalent reset, and native does not have to rely on style `none` alone\n    // to hide an edge whose width was supplied by another contribution.\n    if (found.style === 'none' && found.width === undefined) {\n      found.width = '0'\n    }\n\n    for (const kind of kinds) {\n      const component = found[kind]\n      if (component === undefined) continue\n      const program = programs[kind]\n      program.present = true\n      if (isBase) {\n        program.base = component\n      } else {\n        program.clauses.push({\n          modifiers: value.clauses[clauseIndex].modifiers,\n          payload: component,\n        })\n      }\n    }\n  }\n\n  const entries: Array<{ property: string; value: ParsedValue }> = []\n  for (const kind of kinds) {\n    const program = programs[kind]\n    if (!program.present) continue\n    const shared: ParsedValue = { base: program.base, clauses: program.clauses }\n    for (const longhand of targets[kind]) {\n      // programs are immutable, so every side may alias the same value\n      entries.push({ property: longhand, value: shared })\n    }\n  }\n\n  return { entries, errors }\n}\n"
+  ]
+}

package/types/candidate.d.ts

@@ -0,0 +1,52 @@
+import { type GrammarEntry, type TokenCategory } from "./registry";
+type Names = readonly string[] | ReadonlySet<string> | Readonly<Record<string, unknown>>;
+export interface GrammarConfigView {
+	shorthands?: Readonly<Record<string, string>>;
+	mediaNames?: Names;
+	themeNames?: Names;
+	platformNames?: Names;
+	tokenNames?: Partial<Record<TokenCategory, Names>>;
+	/**
+	* the media keys that measure a size, so `@key:` is a meaningful container
+	* query. derived by createGrammarConfigView when the media input carries
+	* query information; absent means UNKNOWN, and the modifier registry then
+	* refuses container claims with a diagnostic rather than over-claiming
+	*/
+	containerSizeNames?: readonly string[];
+}
+export interface ParsedCandidate {
+	candidate: string;
+	base: string;
+	modifiers: readonly string[];
+	negative: boolean;
+	kind: "utility" | "dynamic";
+	valueKind: "token" | "arbitrary" | "enum" | "convenience";
+	properties?: Readonly<Record<string, string | number>>;
+	entry?: GrammarEntry;
+	prefix?: string;
+	rawValue?: string;
+	arbitrary?: boolean;
+	convenience?: string;
+}
+export type CandidateClassification = {
+	kind: "tamagui";
+	parsed: ParsedCandidate;
+} | {
+	kind: "passthrough";
+	reason: string;
+};
+export declare function hasTokenName(config: GrammarConfigView, category: TokenCategory, name: string): boolean;
+export declare function parseCandidate(candidate: string, config: GrammarConfigView): ParsedCandidate | null;
+export declare function classifyCandidate(candidate: string, config: GrammarConfigView): CandidateClassification;
+export interface FormatCandidateInput {
+	prop: string;
+	value: string;
+	valueKind: ParsedCandidate["valueKind"];
+	modifiers?: readonly string[];
+}
+export declare function formatCandidate({ prop, value, valueKind, modifiers }: FormatCandidateInput, config?: GrammarConfigView): string | null;
+export declare function encodeArbitrary(value: string): string;
+export declare function decodeArbitrary(value: string): string;
+export {};
+
+//# sourceMappingURL=candidate.d.ts.map

package/types/candidate.d.ts.map

@@ -0,0 +1,11 @@
+{
+  "mappings": "AAAA,cAUO,mBACA,qBACA;KAMF,4BAA4B,sBAAsB,SAAS;AAEhE,iBAAiB,kBAAkB;CACjC,aAAa,SAAS;CACtB,aAAa;CACb,aAAa;CACb,gBAAgB;CAChB,aAAa,QAAQ,OAAO,eAAe;;;;;;;CAO3C;;AAGF,iBAAiB,gBAAgB;CAC/B;CACA;CACA;CACA;CACA,MAAM,YAAY;CAClB,WAAW,UAAU,cAAc,SAAS;CAC5C,aAAa,SAAS;CACtB,QAAQ;CACR;CACA;CACA;CACA;;AAGF,YAAY,0BACR;CAAE,MAAM;CAAW,QAAQ;IAC3B;CAAE,MAAM;CAAe;;AA0H3B,OAAO,iBAAS,aACd,QAAQ,mBACR,UAAU,eACV;AAqPF,OAAO,iBAAS,eACd,mBACA,QAAQ,oBACP;AAmFH,OAAO,iBAAS,kBACd,mBACA,QAAQ,oBACP;AAOH,iBAAiB,qBAAqB;CACpC;CACA;CACA,WAAW,gBAAgB;CAC3B;;AAuBF,OAAO,iBAAS,gBACd,EAAE,MAAM,OAAO,WAAW,aAAkB,sBAC5C,SAAS;AAsHX,OAAO,iBAAS,gBAAgB;AAchC,OAAO,iBAAS,gBAAgB",
+  "names": [],
+  "sources": [
+    "src/candidate.ts"
+  ],
+  "version": 3,
+  "sourcesContent": [
+    "import {\n  grammarEntries,\n  fontWeightNames,\n  modifierAliases,\n  prefixToEntries,\n  radiusCornerProps,\n  standaloneValueProps,\n  textAlignKeywords,\n  wholeClassConveniences,\n  wholeClassUtilities,\n  type GrammarEntry,\n  type TokenCategory,\n} from './registry'\nimport { createModifierRegistry } from './modifierRegistry'\nimport { splitColorOpacitySuffix } from './resolvePayload'\nimport { getSafeAreaEdge } from './safeAreaVariables'\nimport type { ModifierKind, ModifierRegistryView } from './valueTypes'\n\ntype Names = readonly string[] | ReadonlySet<string> | Readonly<Record<string, unknown>>\n\nexport interface GrammarConfigView {\n  shorthands?: Readonly<Record<string, string>>\n  mediaNames?: Names\n  themeNames?: Names\n  platformNames?: Names\n  tokenNames?: Partial<Record<TokenCategory, Names>>\n  /**\n   * the media keys that measure a size, so `@key:` is a meaningful container\n   * query. derived by createGrammarConfigView when the media input carries\n   * query information; absent means UNKNOWN, and the modifier registry then\n   * refuses container claims with a diagnostic rather than over-claiming\n   */\n  containerSizeNames?: readonly string[]\n}\n\nexport interface ParsedCandidate {\n  candidate: string\n  base: string\n  modifiers: readonly string[]\n  negative: boolean\n  kind: 'utility' | 'dynamic'\n  valueKind: 'token' | 'arbitrary' | 'enum' | 'convenience'\n  properties?: Readonly<Record<string, string | number>>\n  entry?: GrammarEntry\n  prefix?: string\n  rawValue?: string\n  arbitrary?: boolean\n  convenience?: string\n}\n\nexport type CandidateClassification =\n  | { kind: 'tamagui'; parsed: ParsedCandidate }\n  | { kind: 'passthrough'; reason: string }\n\nconst sizingConveniences = new Set(['full', 'auto', 'screen', 'min', 'max', 'fit'])\nconst fontGenerics = new Set(['sans', 'serif', 'mono'])\nconst numericPattern = /^\\d+(?:\\.\\d+)?$/\nconst extraPrefixes = [\n  'border-x',\n  'border-y',\n  'rounded-t',\n  'rounded-r',\n  'rounded-b',\n  'rounded-l',\n]\nconst negativeTokenProps = new Set([\n  'margin',\n  'marginTop',\n  'marginRight',\n  'marginBottom',\n  'marginLeft',\n  'marginHorizontal',\n  'marginVertical',\n  'top',\n  'right',\n  'bottom',\n  'left',\n  'inset',\n  'x',\n  'y',\n  'letterSpacing',\n])\nconst borderWidthKeywords = new Set(['thin', 'medium', 'thick'])\nconst ambiguousCssKeywords = new Set([\n  'auto',\n  'dashed',\n  'dotted',\n  'double',\n  'groove',\n  'hidden',\n  'inherit',\n  'initial',\n  'inset',\n  'none',\n  'outset',\n  'revert',\n  'revert-layer',\n  'ridge',\n  'solid',\n  'unset',\n])\nconst cssLengthUnits =\n  '(?:px|em|rem|ex|ch|cap|ic|lh|rlh|vw|vh|vmin|vmax|svw|svh|svmin|svmax|lvw|lvh|lvmin|lvmax|dvw|dvh|dvmin|dvmax|cm|mm|q|in|pt|pc)'\nconst cssLengthPattern = new RegExp(`^-?(?:\\\\d+|\\\\d*\\\\.\\\\d+)${cssLengthUnits}$`, 'i')\n\nfunction hasName(names: Names | undefined, name: string): boolean {\n  if (!names) return false\n  if (Array.isArray(names)) return names.includes(name)\n  if (names instanceof Set) return names.has(name)\n  return Object.prototype.hasOwnProperty.call(names, name)\n}\n\nfunction splitCandidate(candidate: string): { modifiers: string[]; base: string } | null {\n  const parts: string[] = []\n  let current = ''\n  let bracketDepth = 0\n  let escaped = false\n  for (const char of candidate) {\n    if (escaped) {\n      current += char\n      escaped = false\n      continue\n    }\n    if (char === '\\\\') {\n      current += char\n      escaped = true\n      continue\n    }\n    if (char === '[') bracketDepth++\n    if (char === ']') bracketDepth--\n    if (char === ':' && bracketDepth === 0) {\n      parts.push(current)\n      current = ''\n    } else {\n      current += char\n    }\n  }\n  if (!current || bracketDepth !== 0) return null\n  return { modifiers: parts, base: current }\n}\n\nconst modifierRegistryCache = new WeakMap<GrammarConfigView, ModifierRegistryView>()\n\nfunction getModifierRegistry(config: GrammarConfigView): ModifierRegistryView {\n  let registry = modifierRegistryCache.get(config)\n  if (!registry) {\n    registry = createModifierRegistry(config).registry\n    modifierRegistryCache.set(config, registry)\n  }\n  return registry\n}\n\nfunction modifierKind(modifier: string, config: GrammarConfigView): ModifierKind | null {\n  const canonical = modifierAliases[modifier] || modifier\n  return getModifierRegistry(config).get(canonical) || null\n}\n\nfunction modifiersAreKnown(\n  modifiers: readonly string[],\n  config: GrammarConfigView\n): boolean {\n  const seen = new Set<ModifierKind>()\n  for (const modifier of modifiers) {\n    const kind = modifierKind(modifier, config)\n    if (!kind || seen.has(kind)) return false\n    seen.add(kind)\n  }\n  return true\n}\n\nfunction hasTokenDomain(config: GrammarConfigView, category: TokenCategory): boolean {\n  return config.tokenNames?.[category] !== undefined\n}\n\nexport function hasTokenName(\n  config: GrammarConfigView,\n  category: TokenCategory,\n  name: string\n): boolean {\n  return hasName(config.tokenNames?.[category], name)\n}\n\nfunction resolveEntries(\n  prefix: string,\n  config: GrammarConfigView\n): readonly GrammarEntry[] {\n  const registered = prefixToEntries[prefix]\n  if (registered) return registered\n  if (prefix === 'border-x' || prefix === 'border-y') {\n    const props =\n      prefix === 'border-x'\n        ? ['borderLeft', 'borderRight']\n        : ['borderTop', 'borderBottom']\n    return grammarEntries.filter((entry) =>\n      props.some((prop) => entry.prop === `${prop}Width` || entry.prop === `${prop}Color`)\n    )\n  }\n  if (prefix.startsWith('rounded-')) {\n    const props = radiusCornerProps[prefix.slice('rounded-'.length)]\n    return props ? grammarEntries.filter((entry) => props.includes(entry.prop)) : []\n  }\n  const expanded = config.shorthands?.[prefix]\n  if (!expanded) return []\n  return grammarEntries.filter((entry) => entry.prop === expanded)\n}\n\nfunction findPrefix(base: string, config: GrammarConfigView): string | null {\n  const prefixes = new Set(Object.keys(prefixToEntries))\n  for (const prefix of extraPrefixes) prefixes.add(prefix)\n  for (const shorthand in config.shorthands) prefixes.add(shorthand)\n  let found: string | null = null\n  for (const prefix of prefixes) {\n    if (base.startsWith(`${prefix}-`) && (!found || prefix.length > found.length)) {\n      found = prefix\n    }\n  }\n  return found\n}\n\nfunction arbitraryInner(rawValue: string): string | null {\n  if (rawValue.length <= 2 || rawValue[0] !== '[' || rawValue.at(-1) !== ']') {\n    return null\n  }\n  const inner = rawValue.slice(1, -1)\n  return arbitraryValueIsBalanced(decodeArbitrary(inner)) ? inner : null\n}\n\nfunction arbitraryValueIsBalanced(value: string): boolean {\n  const opening = new Set(['(', '[', '{'])\n  const matching: Readonly<Record<string, string>> = { ')': '(', ']': '[', '}': '{' }\n  const stack: string[] = []\n  let quote = ''\n  let escaped = false\n  for (const char of value) {\n    if (escaped) {\n      escaped = false\n      continue\n    }\n    if (char === '\\\\') {\n      escaped = true\n      continue\n    }\n    if (quote) {\n      if (char === quote) quote = ''\n      continue\n    }\n    if (char === '\"' || char === \"'\") {\n      quote = char\n      continue\n    }\n    if (opening.has(char)) {\n      stack.push(char)\n      continue\n    }\n    const expected = matching[char]\n    if (expected && stack.pop() !== expected) return false\n  }\n  return !escaped && !quote && stack.length === 0\n}\n\nfunction fractionIsValid(value: string): boolean {\n  const fraction = /^(\\d+)\\/(\\d+)$/.exec(value)\n  return !!fraction && Number(fraction[2]) !== 0\n}\n\nfunction arbitraryBorderKind(value: string): 'width' | 'color' | null {\n  if (/^-?(?:\\d+|\\d*\\.\\d+)$/.test(value)) return 'width'\n  if (cssLengthPattern.test(value) || borderWidthKeywords.has(value)) return 'width'\n  if (/^(?:calc|min|max|clamp)\\(/.test(value)) return 'width'\n  if (ambiguousCssKeywords.has(value) || value.startsWith('var(')) return null\n  if (\n    value.startsWith('#') ||\n    /^(?:rgb|hsl|hwb|lab|lch|oklab|oklch|color|color-mix|light-dark)\\(/.test(value) ||\n    /^[a-zA-Z][a-zA-Z0-9-]*$/.test(value)\n  ) {\n    return 'color'\n  }\n  return null\n}\n\nfunction tokenLookupName(category: TokenCategory, value: string): string {\n  if (category !== 'color') return value\n  const suffix = splitColorOpacitySuffix(value)\n  return suffix.kind === 'none' ? value : suffix.name\n}\n\nfunction chooseEntry(\n  entries: readonly GrammarEntry[],\n  prefix: string,\n  rawValue: string,\n  negative: boolean,\n  config: GrammarConfigView\n): {\n  entry: GrammarEntry\n  valueKind: ParsedCandidate['valueKind']\n  convenience?: string\n} | null {\n  if (getSafeAreaEdge(rawValue)) {\n    const entry = entries.find(\n      ({ tokenCategory }) =>\n        tokenCategory === 'space' ||\n        tokenCategory === 'size' ||\n        tokenCategory === 'radius' ||\n        tokenCategory === 'fontSize' ||\n        tokenCategory === 'lineHeight' ||\n        tokenCategory === 'letterSpacing'\n    )\n    if (entry) {\n      return { entry, valueKind: 'convenience', convenience: 'safe-area' }\n    }\n  }\n\n  const arbitrary = arbitraryInner(rawValue)\n  if (arbitrary !== null) {\n    if (!arbitrary) return null\n    if (prefix.startsWith('border')) {\n      const width = entries.find((entry) => entry.prop.endsWith('Width'))\n      const color = entries.find((entry) => entry.prop.endsWith('Color'))\n      const kind = arbitraryBorderKind(decodeArbitrary(arbitrary))\n      if (!kind || !width || !color) return null\n      return {\n        entry: kind === 'width' ? width : color,\n        valueKind: 'arbitrary',\n      }\n    }\n    if (prefix === 'text') {\n      return {\n        entry: entries.find((entry) => entry.prop === 'fontSize')!,\n        valueKind: 'arbitrary',\n      }\n    }\n    if (prefix === 'font') {\n      return {\n        entry: entries.find((entry) => entry.prop === 'fontFamily')!,\n        valueKind: 'arbitrary',\n      }\n    }\n    return { entry: entries[0], valueKind: 'arbitrary' }\n  }\n\n  if (prefix === 'text') {\n    const fontSize = entries.find((entry) => entry.prop === 'fontSize')\n    if (fontSize && hasTokenName(config, 'fontSize', rawValue)) {\n      return { entry: fontSize, valueKind: 'token' }\n    }\n    if (textAlignKeywords.has(rawValue)) {\n      return {\n        entry: entries.find((entry) => entry.prop === 'textAlign')!,\n        valueKind: 'enum',\n      }\n    }\n    return null\n  }\n\n  if (prefix === 'font') {\n    const fontFamily = entries.find((entry) => entry.prop === 'fontFamily')\n    const fontWeight = entries.find((entry) => entry.prop === 'fontWeight')\n    if (!fontFamily) return null\n    const matchesFamily = hasTokenName(config, 'fontFamily', rawValue)\n    const matchesWeight = fontWeight && hasTokenName(config, 'fontWeight', rawValue)\n    // a name configured as both a family and a weight is ambiguous, like the\n    // border width/color rule above\n    if (matchesFamily && matchesWeight) return null\n    if (matchesFamily) {\n      return { entry: fontFamily, valueKind: 'token' }\n    }\n    if (matchesWeight) {\n      return { entry: fontWeight, valueKind: 'token' }\n    }\n    return fontGenerics.has(rawValue)\n      ? { entry: fontFamily, valueKind: 'convenience', convenience: 'font-generic' }\n      : null\n  }\n\n  if (prefix.startsWith('border')) {\n    const width = entries.find((entry) => entry.prop.endsWith('Width'))\n    const color = entries.find((entry) => entry.prop.endsWith('Color'))\n    const token = negative ? `-${rawValue}` : rawValue\n    const matchesWidth = width && hasTokenName(config, 'space', token)\n    const colorName = tokenLookupName('color', rawValue)\n    const matchesColor = color && hasTokenName(config, 'color', colorName)\n    if (matchesWidth && matchesColor) return null\n    if (matchesWidth) {\n      return { entry: width, valueKind: 'token' }\n    }\n    if (matchesColor) {\n      return { entry: color, valueKind: 'token' }\n    }\n    return null\n  }\n\n  for (const entry of entries) {\n    if (entry.tokenCategory) {\n      const name = negative ? `-${rawValue}` : rawValue\n      const tokenName = tokenLookupName(entry.tokenCategory, name)\n      if (hasTokenName(config, entry.tokenCategory, tokenName)) {\n        return { entry, valueKind: 'token' }\n      }\n      if (\n        entry.tokenCategory === 'size' &&\n        (sizingConveniences.has(rawValue) || fractionIsValid(rawValue))\n      ) {\n        return { entry, valueKind: 'convenience', convenience: 'sizing-keyword' }\n      }\n      if (entry.tokenCategory === 'zIndex' && numericPattern.test(rawValue)) {\n        return { entry, valueKind: 'convenience', convenience: 'integer' }\n      }\n      continue\n    }\n    if (prefix === 'opacity' || prefix === 'scale') {\n      if (numericPattern.test(rawValue)) {\n        return { entry, valueKind: 'convenience', convenience: 'percentage' }\n      }\n      continue\n    }\n    if (entry.prop === 'zIndex' && numericPattern.test(rawValue)) {\n      return { entry, valueKind: 'convenience', convenience: 'integer' }\n    }\n  }\n  return null\n}\n\nexport function parseCandidate(\n  candidate: string,\n  config: GrammarConfigView\n): ParsedCandidate | null {\n  const split = splitCandidate(candidate)\n  if (!split || !modifiersAreKnown(split.modifiers, config)) {\n    return null\n  }\n  const modifiers = split.modifiers.map(\n    (modifier) => modifierAliases[modifier] || modifier\n  )\n\n  const negative = split.base[0] === '-'\n  const core = negative ? split.base.slice(1) : split.base\n  const prefix = findPrefix(core, config)\n  let dynamic:\n    | {\n        prefix: string\n        rawValue: string\n        selected: NonNullable<ReturnType<typeof chooseEntry>>\n      }\n    | undefined\n  if (prefix) {\n    const rawValue = core.slice(prefix.length + 1)\n    if (rawValue) {\n      const entries = resolveEntries(prefix, config)\n      const selected = chooseEntry(entries, prefix, rawValue, negative, config)\n      if (\n        selected &&\n        (!negative ||\n          (selected.valueKind === 'token' && negativeTokenProps.has(selected.entry.prop)))\n      ) {\n        dynamic = { prefix, rawValue, selected }\n        // An exact configured token owns its spelling before a reserved whole utility. Other\n        // dynamic forms defer to the whole utility and are used only when no whole form exists.\n        if (selected.valueKind === 'token') {\n          return {\n            candidate,\n            base: split.base,\n            modifiers,\n            negative,\n            kind: 'dynamic',\n            prefix,\n            rawValue,\n            arbitrary: arbitraryInner(rawValue) !== null,\n            entry: selected.entry,\n            valueKind: selected.valueKind,\n            convenience: selected.convenience,\n          }\n        }\n      }\n    }\n  }\n\n  const direct = wholeClassUtilities[split.base]\n  if (!negative && direct) {\n    const convenience = wholeClassConveniences[split.base]\n    return {\n      candidate,\n      base: split.base,\n      modifiers,\n      kind: 'utility',\n      valueKind: convenience ? 'convenience' : 'enum',\n      properties: direct,\n      convenience,\n      negative: false,\n    }\n  }\n  if (dynamic) {\n    return {\n      candidate,\n      base: split.base,\n      modifiers,\n      negative,\n      kind: 'dynamic',\n      prefix: dynamic.prefix,\n      rawValue: dynamic.rawValue,\n      arbitrary: arbitraryInner(dynamic.rawValue) !== null,\n      entry: dynamic.selected.entry,\n      valueKind: dynamic.selected.valueKind,\n      convenience: dynamic.selected.convenience,\n    }\n  }\n  return null\n}\n\nexport function classifyCandidate(\n  candidate: string,\n  config: GrammarConfigView\n): CandidateClassification {\n  const parsed = parseCandidate(candidate, config)\n  return parsed\n    ? { kind: 'tamagui', parsed }\n    : { kind: 'passthrough', reason: 'not in the configured Tamagui grammar' }\n}\n\nexport interface FormatCandidateInput {\n  prop: string\n  value: string\n  valueKind: ParsedCandidate['valueKind']\n  modifiers?: readonly string[]\n}\n\nfunction tokenValidationConfig(\n  entry: GrammarEntry,\n  value: string,\n  config: GrammarConfigView | undefined\n): GrammarConfigView {\n  const tokenNames: Partial<Record<TokenCategory, Names>> = {\n    ...config?.tokenNames,\n  }\n  const category = entry.tokenCategory!\n  if (tokenNames[category] === undefined) {\n    tokenNames[category] = [tokenLookupName(category, value)]\n  }\n  for (const other of prefixToEntries[entry.prefix] || []) {\n    if (other.tokenCategory && tokenNames[other.tokenCategory] === undefined) {\n      tokenNames[other.tokenCategory] = []\n    }\n  }\n  return { ...config, tokenNames }\n}\n\nexport function formatCandidate(\n  { prop, value, valueKind, modifiers = [] }: FormatCandidateInput,\n  config?: GrammarConfigView\n): string | null {\n  const entry = grammarEntries.find((candidate) => candidate.prop === prop)\n  if (!entry) return null\n  if (valueKind === 'arbitrary' && value === '') return null\n  if (!modifiersAreKnown(modifiers, config || {})) return null\n  const normalizedModifiers = modifiers.map(\n    (modifier) => modifierAliases[modifier] || modifier\n  )\n\n  if (valueKind === 'enum') {\n    const whole = standaloneValueProps[prop]?.[value]\n    if (whole) {\n      const candidate = normalizedModifiers.length\n        ? `${normalizedModifiers.join(':')}:${whole}`\n        : whole\n      if (config) {\n        const parsed = parseCandidate(candidate, config)\n        if (!parsed?.properties || parsed.properties[prop] !== value) return null\n      }\n      return candidate\n    }\n    if (prop === 'fontWeight') {\n      const name = fontWeightNames[value]\n      if (!name) return null\n      const core = `font-${name}`\n      if (String(wholeClassUtilities[core]?.fontWeight) !== value) return null\n      const candidate = normalizedModifiers.length\n        ? `${normalizedModifiers.join(':')}:${core}`\n        : core\n      if (config) {\n        const parsed = parseCandidate(candidate, config)\n        if (!parsed?.properties || String(parsed.properties.fontWeight) !== value) {\n          return null\n        }\n      }\n      return candidate\n    }\n  }\n  if (!entry.prefix) return null\n  if (valueKind === 'token') {\n    if (!entry.tokenCategory) return null\n    const sourceDomainKnown = !!config && hasTokenDomain(config, entry.tokenCategory)\n    const lookupName = tokenLookupName(entry.tokenCategory, value)\n    if (sourceDomainKnown && !hasTokenName(config!, entry.tokenCategory, lookupName))\n      return null\n    const colliding = prefixToEntries[entry.prefix].filter(\n      (other) => other.prop !== prop && other.tokenCategory\n    )\n    if (colliding.length) {\n      if (!config || !sourceDomainKnown) return null\n      for (const other of colliding) {\n        if (!hasTokenDomain(config, other.tokenCategory!)) return null\n        if (hasTokenName(config, other.tokenCategory!, value)) return null\n      }\n    }\n  }\n  const formattedValue = valueKind === 'arbitrary' ? `[${encodeArbitrary(value)}]` : value\n  const core =\n    formattedValue[0] === '-' && formattedValue[1] !== '['\n      ? `-${entry.prefix}-${formattedValue.slice(1)}`\n      : formattedValue\n        ? `${entry.prefix}-${formattedValue}`\n        : entry.prefix\n  const candidate = normalizedModifiers.length\n    ? `${normalizedModifiers.join(':')}:${core}`\n    : core\n  const whole = wholeClassUtilities[core]\n  if (whole) {\n    if (valueKind === 'token') {\n      if (!config || !hasTokenDomain(config, entry.tokenCategory!)) return null\n    } else if (config) {\n      const parsed = parseCandidate(candidate, config)\n      if (parsed?.kind === 'utility') {\n        return Object.prototype.hasOwnProperty.call(parsed.properties, prop) &&\n          String(parsed.properties?.[prop]) === value\n          ? candidate\n          : null\n      }\n      return parsed?.entry?.prop === prop && parsed.valueKind === valueKind\n        ? candidate\n        : null\n    } else if (\n      Object.prototype.hasOwnProperty.call(whole, prop) &&\n      String(whole[prop]) === value\n    ) {\n      return candidate\n    } else {\n      return null\n    }\n  }\n  if (valueKind === 'token') {\n    if (\n      !hasTokenDomain(config || {}, entry.tokenCategory!) &&\n      parseCandidate(candidate, config || {})\n    ) {\n      return null\n    }\n    const parsed = parseCandidate(candidate, tokenValidationConfig(entry, value, config))\n    const parsedValue = parsed?.rawValue\n      ? `${parsed.negative ? '-' : ''}${parsed.rawValue}`\n      : null\n    if (\n      parsed?.kind !== 'dynamic' ||\n      parsed.entry?.prop !== prop ||\n      parsed.valueKind !== 'token' ||\n      parsedValue !== value\n    ) {\n      return null\n    }\n    return candidate\n  }\n  const parsed = parseCandidate(candidate, config || {})\n  if (!parsed || parsed.entry?.prop !== prop || parsed.valueKind !== valueKind)\n    return null\n  return candidate\n}\n\nexport function encodeArbitrary(value: string): string {\n  let encoded = ''\n  for (const char of value) {\n    if (char === '\\\\' || char === '_' || char === '[' || char === ']') {\n      encoded += `\\\\${char}`\n    } else if (/\\s/.test(char)) {\n      encoded += '_'\n    } else {\n      encoded += char\n    }\n  }\n  return encoded\n}\n\nexport function decodeArbitrary(value: string): string {\n  let decoded = ''\n  for (let index = 0; index < value.length; index++) {\n    const char = value[index]\n    if (char === '\\\\' && index + 1 < value.length) {\n      decoded += value[++index]\n    } else {\n      decoded += char === '_' ? ' ' : char\n    }\n  }\n  return decoded\n}\n"
+  ]
+}

package/types/candidateTarget.d.ts

@@ -0,0 +1,32 @@
+import type { TokenCategory } from "./registry";
+export interface CandidateContribution {
+	property: string;
+	/** the token category this contribution binds through, when config-derived */
+	tokenCategory?: TokenCategory;
+}
+export interface CandidatePropertyMismatch {
+	code: "candidate-property-mismatch";
+	candidate: string;
+	property: string;
+	contributedProperties: readonly string[];
+	message: string;
+}
+export type CandidateTargetResult<Contribution extends CandidateContribution> = {
+	ok: true;
+	contribution: Contribution;
+} | {
+	ok: false;
+	diagnostic: CandidatePropertyMismatch;
+};
+/**
+* selects the contribution addressed by an overloaded family prop.
+*
+* candidate resolution happens before this function, so both the compiler and
+* runtime pass the same family contributions here. A candidate is valid only
+* when it contributes to the authored property itself. This keeps shared
+* families such as `text-*` from accepting a color candidate for `fontSize`,
+* or a font-size candidate for `color`.
+*/
+export declare function resolveCandidateTarget<Contribution extends CandidateContribution>(property: string, candidate: string, contributions: readonly Contribution[]): CandidateTargetResult<Contribution>;
+
+//# sourceMappingURL=candidateTarget.d.ts.map

package/types/candidateTarget.d.ts.map

@@ -0,0 +1,11 @@
+{
+  "mappings": "AAAA,cAAc,qBAAqB;AAEnC,iBAAiB,sBAAsB;CACrC;;CAEA,gBAAgB;;AAGlB,iBAAiB,0BAA0B;CACzC,MAAM;CACN;CACA;CACA;CACA;;AAGF,YAAY,sBAAsB,qBAAqB,yBACnD;CACE,IAAI;CACJ,cAAc;IAEhB;CACE,IAAI;CACJ,YAAY;;;;;;;;;;;AAYlB,OAAO,iBAAS,uBAAuB,qBAAqB,uBAC1D,kBACA,mBACA,wBAAwB,iBACvB,sBAAsB",
+  "names": [],
+  "sources": [
+    "src/candidateTarget.ts"
+  ],
+  "version": 3,
+  "sourcesContent": [
+    "import type { TokenCategory } from './registry'\n\nexport interface CandidateContribution {\n  property: string\n  /** the token category this contribution binds through, when config-derived */\n  tokenCategory?: TokenCategory\n}\n\nexport interface CandidatePropertyMismatch {\n  code: 'candidate-property-mismatch'\n  candidate: string\n  property: string\n  contributedProperties: readonly string[]\n  message: string\n}\n\nexport type CandidateTargetResult<Contribution extends CandidateContribution> =\n  | {\n      ok: true\n      contribution: Contribution\n    }\n  | {\n      ok: false\n      diagnostic: CandidatePropertyMismatch\n    }\n\n/**\n * selects the contribution addressed by an overloaded family prop.\n *\n * candidate resolution happens before this function, so both the compiler and\n * runtime pass the same family contributions here. A candidate is valid only\n * when it contributes to the authored property itself. This keeps shared\n * families such as `text-*` from accepting a color candidate for `fontSize`,\n * or a font-size candidate for `color`.\n */\nexport function resolveCandidateTarget<Contribution extends CandidateContribution>(\n  property: string,\n  candidate: string,\n  contributions: readonly Contribution[]\n): CandidateTargetResult<Contribution> {\n  for (const contribution of contributions) {\n    if (contribution.property === property) {\n      return { ok: true, contribution }\n    }\n  }\n\n  const contributedProperties: string[] = []\n  for (const contribution of contributions) {\n    if (!contributedProperties.includes(contribution.property)) {\n      contributedProperties.push(contribution.property)\n    }\n  }\n\n  return {\n    ok: false,\n    diagnostic: {\n      code: 'candidate-property-mismatch',\n      candidate,\n      property,\n      contributedProperties,\n      message:\n        contributedProperties.length === 0\n          ? `\"${candidate}\" does not contribute to \"${property}\"`\n          : `\"${candidate}\" contributes to ${contributedProperties.map((name) => `\"${name}\"`).join(', ')}, not \"${property}\"`,\n    },\n  }\n}\n"
+  ]
+}

package/types/clauseCapability.d.ts

@@ -0,0 +1,69 @@
+import type { ModifierKind, ModifierRegistryView } from "./valueTypes";
+export interface ClauseCapability {
+	/** the clause can lower to web CSS */
+	web: boolean;
+	/** the clause can evaluate on native */
+	native: boolean;
+	/** why a side is unsupported, for diagnostics */
+	note?: string;
+}
+/**
+* Per-modifier capability. `kind` comes from the same registry the value was
+* parsed against; an unregistered modifier is a parse error upstream and
+* reports unsupported on both targets here.
+*/
+export declare function clauseCapability(modifier: string, kind: ModifierKind | undefined): ClauseCapability;
+/** file-extension intent: shared files must support BOTH targets */
+export type ConversionTargets = "shared" | "web" | "native";
+/**
+* Host validity as the consumer already holds it — a projection of the
+* component's staticConfig, never a table of this package's own.
+*/
+export interface HostView {
+	/** does this host accept `prop` as a style (validStyles + accept) */
+	accepts(prop: string): boolean;
+	/** for diagnostics: the component label the author sees */
+	displayName?: string;
+}
+export interface ConversionReason {
+	dimension: "property" | "clause" | "host";
+	modifier?: string;
+	message: string;
+	/** the action the author takes, stated concretely */
+	remedy: string;
+}
+export interface ConversionAssessment {
+	/**
+	* clean: convertible AND evaluable where authored, with ALL THREE
+	* dimensions verified — clean is a promise, so an unchecked dimension can
+	* never produce it. needs-relocation: the conversion is syntactically
+	* right but this site was DETERMINED unable to evaluate it — the remedy
+	* names where it goes. unknown-host: property and clauses verified but the
+	* component identity could not be established, so host validity is
+	* UNVERIFIED rather than fine — the site needs review, not relocation.
+	* ineligible: this property cannot carry the clause spelling at all.
+	*/
+	verdict: "clean" | "needs-relocation" | "unknown-host" | "ineligible";
+	reasons: readonly ConversionReason[];
+}
+export interface ConversionInput {
+	property: string;
+	/** modifiers used across the value's clauses, deduplicated by the caller or not */
+	modifiers?: readonly string[];
+	targets: ConversionTargets;
+	/**
+	* absent means the consumer could NOT establish the component's identity
+	* (structural provenance proves only direct View/Text and traceable styled
+	* bases today) — the verdict is then at best 'unknown-host', never 'clean'
+	*/
+	host?: HostView;
+}
+/**
+* The one call a converter, lint rule, or report makes before claiming a
+* flat-value suggestion is safe. Composes property eligibility, per-target
+* clause capability, and host validity; consumers never combine axes
+* themselves.
+*/
+export declare function assessFlatConversion(input: ConversionInput, registry: ModifierRegistryView): ConversionAssessment;
+
+//# sourceMappingURL=clauseCapability.d.ts.map