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

package/src/candidateTarget.ts

@@ -0,0 +1,67 @@
+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 function resolveCandidateTarget<Contribution extends CandidateContribution>(
+  property: string,
+  candidate: string,
+  contributions: readonly Contribution[]
+): CandidateTargetResult<Contribution> {
+  for (const contribution of contributions) {
+    if (contribution.property === property) {
+      return { ok: true, contribution }
+    }
+  }
+
+  const contributedProperties: string[] = []
+  for (const contribution of contributions) {
+    if (!contributedProperties.includes(contribution.property)) {
+      contributedProperties.push(contribution.property)
+    }
+  }
+
+  return {
+    ok: false,
+    diagnostic: {
+      code: 'candidate-property-mismatch',
+      candidate,
+      property,
+      contributedProperties,
+      message:
+        contributedProperties.length === 0
+          ? `"${candidate}" does not contribute to "${property}"`
+          : `"${candidate}" contributes to ${contributedProperties.map((name) => `"${name}"`).join(', ')}, not "${property}"`,
+    },
+  }
+}

package/src/clauseCapability.ts

@@ -0,0 +1,209 @@
+// The platform-clause capability contract and the composed conversion
+// assessment (three-dimension review, 2026-07-31).
+//
+// Three separately-owned dimensions, one composed answer:
+// - PROPERTY: programEligibility (can this prop carry programs at all).
+// - CLAUSE (this file): can a modifier lower on web CSS, and can it evaluate
+//   natively. This is the ONE owner of both capability sets — the web side is
+//   DERIVED from the lowering selector table and the native side is defined
+//   here and consumed by the native evaluator, so the claims cannot drift
+//   from what actually runs.
+// - HOST: owned by the validStyles tables in @tamagui/helpers (enforced at
+//   runtime by the text-only-prop ruling). NOT mirrored here — the consumer
+//   supplies a HostView it already holds (staticConfig for the runtime and
+//   codemod, the serialized config for tooling).
+//
+// The composition lives INSIDE assessFlatConversion so no consumer ever
+// combines axes itself: one question, one structured answer, and "clean"
+// means convertible AND evaluable where the author put it.
+
+import { legacyPartComposite, programEligibility } from './programEligibility'
+import { defaultStateSelectors } from './lowerProgram'
+import { parseContainerModifier, parseGroupModifier } from './modifierRegistry'
+import { nativeGroupSourceableStates, nativeSourceableStates } from './clauseSources'
+import type { ModifierKind, ModifierRegistryView } from './valueTypes'
+
+const nativeGroupSourceable: ReadonlySet<string> = new Set(nativeGroupSourceableStates)
+
+/**
+ * Web lowerability is DERIVED from the selector table the lowering actually
+ * uses, including the lifecycle classes emitted by createComponent.
+ */
+const webLowerableStates: ReadonlySet<string> = new Set(
+  Object.keys(defaultStateSelectors)
+)
+
+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
+}
+
+const bothTargets: ClauseCapability = Object.freeze({ web: true, native: true })
+
+/**
+ * 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 function clauseCapability(
+  modifier: string,
+  kind: ModifierKind | undefined
+): ClauseCapability {
+  if (kind === 'media' || kind === 'theme' || kind === 'platform') {
+    return bothTargets
+  }
+  if (kind === 'container') {
+    return bothTargets
+  }
+  if (kind === 'state') {
+    const web = webLowerableStates.has(modifier)
+    const native = nativeSourceableStates.has(modifier)
+    if (web && native) return bothTargets
+    return {
+      web,
+      native,
+      note: !web
+        ? `"${modifier}:" cannot lower to web CSS because it has no selector`
+        : `"${modifier}:" is a component-tier state with no native source until the behavior packages feed componentState`,
+    }
+  }
+  if (kind === 'group') {
+    const parsed = parseGroupModifier(modifier)
+    if (!parsed)
+      return { web: false, native: false, note: `"${modifier}:" is not a group modifier` }
+    const web = webLowerableStates.has(parsed.state)
+    const native = nativeGroupSourceable.has(parsed.state)
+    if (web && native) return bothTargets
+    return {
+      web,
+      native,
+      note: `group state "${parsed.state}" has no native source`,
+    }
+  }
+  return {
+    web: false,
+    native: false,
+    note: `"${modifier}:" is not a registered modifier`,
+  }
+}
+
+/** 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
+}
+
+const clean: ConversionAssessment = Object.freeze({ verdict: 'clean', reasons: [] })
+
+/**
+ * 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 function assessFlatConversion(
+  input: ConversionInput,
+  registry: ModifierRegistryView
+): ConversionAssessment {
+  const reasons: ConversionReason[] = []
+
+  if (programEligibility(input.property) === 'legacy-part') {
+    reasons.push({
+      dimension: 'property',
+      message: `"${input.property}" is a part prop with no flat clause spelling`,
+      remedy: `move the condition onto \`${legacyPartComposite[input.property]}\``,
+    })
+    return { verdict: 'ineligible', reasons }
+  }
+
+  for (const modifier of input.modifiers ?? []) {
+    const capability = clauseCapability(modifier, registry.get(modifier))
+    const needsWeb = input.targets !== 'native'
+    const needsNative = input.targets !== 'web'
+    if ((needsWeb && !capability.web) || (needsNative && !capability.native)) {
+      const missing = needsWeb && !capability.web ? 'web' : 'native'
+      reasons.push({
+        dimension: 'clause',
+        modifier,
+        message: capability.note ?? `"${modifier}:" is not supported on ${missing}`,
+        remedy:
+          missing === 'web'
+            ? `keep the driver-evaluated pseudo prop, or move this usage to a .native.tsx file`
+            : `move this usage to a .web.tsx file, or drop the clause on native`,
+      })
+    }
+  }
+
+  if (input.host && !input.host.accepts(input.property)) {
+    reasons.push({
+      dimension: 'host',
+      message: `"${input.property}" is not a valid style on ${input.host.displayName ?? 'this component'} — the runtime drops it`,
+      remedy: `move this style to a component that accepts it (a Text-based component, or html.* on web)`,
+    })
+  }
+
+  if (reasons.length) return { verdict: 'needs-relocation', reasons }
+
+  if (!input.host) {
+    return {
+      verdict: 'unknown-host',
+      reasons: [
+        {
+          dimension: 'host',
+          message: `the component's identity could not be established, so host validity for "${input.property}" is unverified`,
+          remedy: `verify the component accepts this style prop, or supply type-aware provenance so the check can run`,
+        },
+      ],
+    }
+  }
+
+  return clean
+}

package/src/clausePrecedence.ts

@@ -0,0 +1,198 @@
+import { grammarPlatformRank } from './config'
+import {
+  canonicalClauseModifier,
+  parseContainerModifier,
+  parseGroupModifier,
+} from './modifierRegistry'
+
+export { canonicalClauseModifier } from './modifierRegistry'
+import {
+  grammarMaxNonPlatformDepth,
+  type ModifierKind,
+  type ModifierRegistryView,
+} from './valueTypes'
+
+export { grammarMaxNonPlatformDepth } from './valueTypes'
+
+/**
+ * The CSS emitter deliberately caps a condition chain at five distinct
+ * non-platform conditions. The parser can represent longer chains, but they
+ * cannot be lowered while also giving platform clauses a finite specificity
+ * floor above every platform-less clause, so the shared comparator rejects
+ * them consistently on every surface.
+ */
+export type ClausePrecedenceKey = readonly [
+  /** no platform = 0; web/native = 1; ios/android/tv = 2; tvos/androidtv = 3 */
+  platformRank: number,
+  /** number of distinct non-platform conditions */
+  depth: number,
+  /** media < container < theme < group < state */
+  categoryRank: number,
+  /** declaration/lifecycle rank inside the highest category */
+  withinCategoryRank: number,
+]
+
+export type OrderedModifierNames =
+  | readonly string[]
+  | ReadonlySet<string>
+  | Readonly<Record<string, unknown>>
+
+export type ClausePrecedenceOrder = ReadonlyMap<string, number>
+
+const categoryRanks: Readonly<Record<Exclude<ModifierKind, 'platform'>, number>> = {
+  media: 0,
+  container: 1,
+  theme: 2,
+  group: 3,
+  state: 4,
+}
+
+// Later lifecycle entries win. Component-tier states follow the interaction
+// states in the order of states.ts's component vocabulary.
+const stateRanks: Readonly<Record<string, number>> = Object.freeze({
+  hover: 0,
+  'focus-within': 1,
+  focus: 2,
+  'focus-visible': 3,
+  press: 4,
+  active: 4,
+  pressed: 4,
+  disabled: 5,
+  enter: 6,
+  starting: 6,
+  exit: 7,
+  ending: 7,
+  open: 8,
+  checked: 9,
+  highlighted: 10,
+  selected: 11,
+  invalid: 12,
+})
+
+export function createClausePrecedenceOrder(
+  names: OrderedModifierNames | undefined
+): ClausePrecedenceOrder {
+  const ranks = new Map<string, number>()
+  if (!names) return ranks
+  let rank = 0
+  if (Array.isArray(names)) {
+    for (const name of names) ranks.set(name, rank++)
+  } else if (names instanceof Set) {
+    for (const name of names) ranks.set(name, rank++)
+  } else {
+    for (const name in names as Readonly<Record<string, unknown>>) {
+      ranks.set(name, rank++)
+    }
+  }
+  return ranks
+}
+
+function withinCategoryRank(
+  modifier: string,
+  kind: Exclude<ModifierKind, 'platform'>,
+  order: ClausePrecedenceOrder
+): number {
+  if (kind === 'media') return order.get(modifier) ?? 0
+  if (kind === 'container') {
+    const container = parseContainerModifier(modifier)
+    return container ? (order.get(container.size) ?? 0) : 0
+  }
+  if (kind === 'theme') return 0
+  if (kind === 'group') {
+    const group = parseGroupModifier(modifier)
+    return group ? (stateRanks[group.state] ?? 0) : 0
+  }
+  return stateRanks[modifier] ?? 0
+}
+
+/** Order-insensitive set key used by every clause merge/emission slot. */
+export function clauseConditionSetKey(modifiers: readonly string[]): string {
+  if (modifiers.length === 0) return ''
+  if (modifiers.length === 1) return canonicalClauseModifier(modifiers[0])
+  const unique = new Set(modifiers.map(canonicalClauseModifier))
+  return [...unique].sort().join(':')
+}
+
+export function getClausePrecedenceKeyFromKinds(
+  modifiers: readonly string[],
+  kinds: readonly (ModifierKind | undefined)[],
+  order: ClausePrecedenceOrder
+): ClausePrecedenceKey {
+  let platformRank = 0
+  let categoryRank = 0
+  let highestWithinCategoryRank = 0
+  const nonPlatform = new Set<string>()
+
+  for (let index = 0; index < modifiers.length; index++) {
+    const modifier = canonicalClauseModifier(modifiers[index])
+    const kind = kinds[index]
+    if (!kind) continue
+    if (kind === 'platform') {
+      platformRank = Math.max(platformRank, grammarPlatformRank(modifier))
+      continue
+    }
+
+    nonPlatform.add(modifier)
+    const nextCategoryRank = categoryRanks[kind]
+    const nextWithinCategoryRank = withinCategoryRank(modifier, kind, order)
+    if (nextCategoryRank > categoryRank) {
+      categoryRank = nextCategoryRank
+      highestWithinCategoryRank = nextWithinCategoryRank
+    } else if (nextCategoryRank === categoryRank) {
+      highestWithinCategoryRank = Math.max(
+        highestWithinCategoryRank,
+        nextWithinCategoryRank
+      )
+    }
+  }
+
+  const depth = nonPlatform.size
+  if (depth > grammarMaxNonPlatformDepth) {
+    throw new Error(
+      `a flat value clause supports at most ${grammarMaxNonPlatformDepth} non-platform conditions; received ${depth} in "${modifiers.join(':')}:"`
+    )
+  }
+
+  return [platformRank, depth, categoryRank, highestWithinCategoryRank]
+}
+
+export function getClausePrecedenceKey(
+  modifiers: readonly string[],
+  registry: ModifierRegistryView,
+  order: ClausePrecedenceOrder
+): ClausePrecedenceKey {
+  const kinds: (ModifierKind | undefined)[] = []
+  for (let index = 0; index < modifiers.length; index++) {
+    kinds.push(registry.get(modifiers[index]))
+  }
+  return getClausePrecedenceKeyFromKinds(modifiers, kinds, order)
+}
+
+/** Ascending comparator: a positive result means `left` wins over `right`. */
+export function compareClausePrecedence(
+  left: ClausePrecedenceKey,
+  right: ClausePrecedenceKey
+): number {
+  for (let index = 0; index < 4; index++) {
+    const difference = left[index] - right[index]
+    if (difference) return difference
+  }
+  return 0
+}
+
+/** Target CSS class specificity, excluding IDs/elements: (0, result, 0). */
+export function clauseTargetClassSpecificity(key: ClausePrecedenceKey): number {
+  return 1 + key[1] + key[0] * (grammarMaxNonPlatformDepth + 1)
+}
+
+/**
+ * Subject-class repetitions needed after self-state selectors contribute
+ * their pseudo/attribute specificity naturally. Theme and group scopes use
+ * :where(), while media/container wrappers contribute zero.
+ */
+export function clauseSubjectClassRepetitions(
+  key: ClausePrecedenceKey,
+  selfStateSpecificity: number
+): number {
+  return clauseTargetClassSpecificity(key) - selfStateSpecificity
+}

package/src/clauseSources.ts

@@ -0,0 +1,29 @@
+/**
+ * states the native evaluator can source from component state and lifecycle.
+ * component-tier states stay web-only until their behavior packages feed them
+ * into component state.
+ */
+export const nativeSourceableStates: ReadonlySet<string> = new Set([
+  'hover',
+  'press',
+  'active',
+  'focus',
+  'focus-visible',
+  'focus-within',
+  'disabled',
+  'enter',
+  'exit',
+])
+
+/**
+ * states a group clause can source natively through componentState.group.
+ */
+export const nativeGroupSourceableStates: readonly string[] = Object.freeze([
+  'hover',
+  'press',
+  'active',
+  'focus',
+  'focus-visible',
+  'focus-within',
+  'disabled',
+])

package/src/config.ts

@@ -0,0 +1,169 @@
+import type { GrammarConfigView } from './candidate'
+import type { TokenCategory } from './registry'
+
+type Names = readonly string[] | ReadonlySet<string> | Readonly<Record<string, unknown>>
+
+type GrammarFontConfig = {
+  size?: Readonly<Record<string, unknown>>
+  weight?: Readonly<Record<string, unknown>>
+  lineHeight?: Readonly<Record<string, unknown>>
+  letterSpacing?: Readonly<Record<string, unknown>>
+}
+
+export type GrammarSourceConfig = {
+  shorthands?: Readonly<Record<string, string>>
+  media?: Names
+  themes?: Readonly<Record<string, unknown>>
+  tokensParsed?: Partial<
+    Record<
+      'space' | 'size' | 'radius' | 'zIndex' | 'color',
+      Readonly<Record<string, unknown>>
+    >
+  >
+  fontsParsed?: Readonly<Record<string, GrammarFontConfig | undefined>>
+}
+
+export type CreateGrammarConfigViewOptions = {
+  platformNames?: Names
+  /** overrides the derived container size set (the web adapter's resolved set) */
+  containerSizeNames?: readonly string[]
+}
+
+/**
+ * The one owner of "does this media query measure a size". A `hover` or
+ * `pointer` key measures nothing a container has, so it gets no `@` form.
+ * Accepts the query TEXT (`(min-width: 900px)`) or the config's media OBJECT
+ * (`{ minWidth: 900 }`) — both spellings of the same fact.
+ */
+export function isContainerSizeQuery(query: unknown): boolean {
+  if (typeof query === 'string') {
+    return (
+      query.includes('width') ||
+      query.includes('height') ||
+      query.includes('inline-size') ||
+      query.includes('block-size')
+    )
+  }
+  if (query && typeof query === 'object') {
+    for (const key in query as Readonly<Record<string, unknown>>) {
+      if (/width|height|size/i.test(key)) return true
+    }
+  }
+  return false
+}
+
+export const grammarPlatformNames: ReadonlySet<string> = new Set([
+  'web',
+  'native',
+  'android',
+  'ios',
+  'tv',
+  'androidtv',
+  'tvos',
+])
+
+export const grammarPlatformGroups: ReadonlyMap<string, ReadonlySet<string>> = new Map([
+  ['native', new Set(['android', 'ios', 'androidtv', 'tvos'])],
+  ['tv', new Set(['androidtv', 'tvos'])],
+  // react-native-tvos reports Platform.OS 'android'/'ios' on TV devices, so the
+  // base platform contains its TV variant (matches runtime platformMatches)
+  ['android', new Set(['androidtv'])],
+  ['ios', new Set(['tvos'])],
+])
+
+/**
+ * Platform clause specificity, mirroring the runtime directStyle ranks: a TV
+ * variant beats its base platform, which beats `native`, independent of
+ * authored order. Non-platform modifiers never rank.
+ */
+export function grammarPlatformRank(modifier: string): number {
+  return modifier === 'native' || modifier === 'web'
+    ? 1
+    : modifier === 'androidtv' || modifier === 'tvos'
+      ? 3
+      : 2
+}
+
+function addNames(target: Set<string>, source: Names | undefined): void {
+  if (!source) return
+  if (Array.isArray(source)) {
+    for (const key of source) target.add(key)
+    return
+  }
+  if (source instanceof Set) {
+    for (const key of source) target.add(key)
+    return
+  }
+  for (const key in source) target.add(key)
+}
+
+/**
+ * Creates the dependency-free config projection consumed by the shared style grammar.
+ * Runtime and compiler integrations must classify candidates through this same view so
+ * a candidate cannot be claimed by one side and emitted by the other.
+ */
+export function createGrammarConfigView(
+  config: GrammarSourceConfig,
+  options: CreateGrammarConfigViewOptions = {}
+): GrammarConfigView {
+  const tokenNames: Record<TokenCategory, Set<string>> = {
+    space: new Set(),
+    size: new Set(),
+    radius: new Set(),
+    zIndex: new Set(),
+    color: new Set(),
+    fontFamily: new Set(),
+    fontSize: new Set(),
+    fontWeight: new Set(),
+    lineHeight: new Set(),
+    letterSpacing: new Set(),
+  }
+
+  for (const category of ['space', 'size', 'radius', 'zIndex', 'color'] as const) {
+    addNames(tokenNames[category], config.tokensParsed?.[category])
+  }
+
+  for (const themeName in config.themes) {
+    const theme = config.themes[themeName]
+    if (theme && typeof theme === 'object' && !Array.isArray(theme)) {
+      addNames(tokenNames.color, theme as Readonly<Record<string, unknown>>)
+    }
+  }
+
+  for (const familyName in config.fontsParsed) {
+    tokenNames.fontFamily.add(familyName)
+    const font = config.fontsParsed[familyName]
+    addNames(tokenNames.fontSize, font?.size)
+    addNames(tokenNames.fontWeight, font?.weight)
+    addNames(tokenNames.lineHeight, font?.lineHeight)
+    addNames(tokenNames.letterSpacing, font?.letterSpacing)
+  }
+
+  // container size derivation needs query information, which only the
+  // record form of `media` carries (values are media objects or query text).
+  // a bare name list stays undefined = unknown, and the modifier registry
+  // refuses container claims for it rather than guessing
+  let containerSizeNames = options.containerSizeNames
+  if (
+    containerSizeNames === undefined &&
+    config.media &&
+    !Array.isArray(config.media) &&
+    !(config.media instanceof Set)
+  ) {
+    const derived: string[] = []
+    const media = config.media as Readonly<Record<string, unknown>>
+    for (const key in media) {
+      if (isContainerSizeQuery(media[key])) derived.push(key)
+    }
+    containerSizeNames = derived
+  }
+
+  return {
+    shorthands: config.shorthands,
+    mediaNames: config.media,
+    themeNames: config.themes,
+    platformNames: options.platformNames ?? grammarPlatformNames,
+    tokenNames,
+    containerSizeNames,
+  }
+}