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

package/src/modifierRegistry.ts

@@ -0,0 +1,340 @@
+// The one global modifier namespace the flat value grammar parses against.
+//
+// Built from the existing built-in state vocabulary plus the config's media
+// keys, platform names, and root theme names, with parameterized group
+// modifiers resolved on lookup. There is a single namespace on purpose: a name
+// may mean exactly one thing, so a config whose media key collides with a state
+// or theme name gets a diagnostic instead of a silent choice. Registration order
+// is state, media, platform, theme, and first registration wins.
+//
+// See plans/dom-tailwind-flat-values.md — "Conditions".
+
+import type { GrammarConfigView } from './candidate'
+import { grammarPlatformNames } from './config'
+import { coreStateModifierNames, modifierAliases } from './stateModifiers'
+import { componentStateNames } from './states'
+import {
+  grammarMaxNonPlatformDepth,
+  type ModifierKind,
+  type ModifierRegistryView,
+} from './valueTypes'
+
+type Names = readonly string[] | ReadonlySet<string> | Readonly<Record<string, unknown>>
+
+export interface ModifierRegistryResult {
+  registry: ModifierRegistryView
+  /** one human-readable line per name collision, in registration order */
+  diagnostics: string[]
+}
+
+export interface CreateModifierRegistryOptions {
+  /**
+   * The media keys that measure a size, so `@key` is a meaningful container
+   * query. A `hover` or `pointer` media key measures nothing a container has, and
+   * `@container (hover: none)` is valid syntax with no meaning, so those keys have
+   * no `@` form.
+   *
+   * Overrides the view's derived `containerSizeNames`. When NEITHER is
+   * supplied the sizes are unknown: no container modifier registers and a
+   * diagnostic says so — an unknowable set refuses rather than over-claims.
+   * A caller with genuinely no container concept passes `[]` explicitly.
+   */
+  containerSizeNames?: Names
+}
+
+/**
+ * Every built-in interaction/state modifier spelling: the modifiers of the core
+ * pseudo-style props, their aliases, and the component-tier state words the
+ * behavior packages expose through DOM attributes.
+ */
+export const stateModifierNames: readonly string[] = Object.freeze([
+  ...coreStateModifierNames,
+  ...Object.keys(modifierAliases),
+  ...componentStateNames,
+])
+
+const stateModifierSet: ReadonlySet<string> = new Set(stateModifierNames)
+
+const groupPrefixLength = 'group-'.length
+
+/**
+ * Theme conditions name a root theme. Nested themes still inherit from that
+ * root, so `dark:` applies within `dark_blue`, but `dark_blue:` is not a
+ * condition of its own.
+ */
+export function isRootThemeName(name: string): boolean {
+  return name.length > 0 && !name.includes('_')
+}
+
+export interface GroupModifier {
+  /** the state the parent group must be in, always a built-in state modifier */
+  state: string
+  /** the group name, or null for the nearest unnamed group */
+  group: string | null
+}
+
+/** Canonical spelling used by slot identity, precedence, hashing, and matching. */
+export function canonicalClauseModifier(name: string): string {
+  const direct = modifierAliases[name]
+  if (direct) return direct
+  if (name.startsWith('group-')) {
+    const group = parseGroupModifier(name)
+    if (group) {
+      const state = modifierAliases[group.state] ?? group.state
+      if (state !== group.state) {
+        return group.group === null ? `group-${state}` : `group-${state}/${group.group}`
+      }
+    }
+  }
+  return name
+}
+
+/**
+ * Parameterized group modifiers use Tailwind's spelling: `group-hover` for the
+ * nearest unnamed group and `group-hover/card` for a named one. The state part
+ * must be a built-in state modifier; the name part is an identifier. Returns
+ * null for anything else, which is what makes the spelling a single source of
+ * truth for both registration and lowering.
+ */
+export function parseGroupModifier(name: string): GroupModifier | null {
+  if (!name.startsWith('group-')) return null
+  const slash = name.indexOf('/')
+  if (slash === -1) {
+    const state = name.slice(groupPrefixLength)
+    return stateModifierSet.has(state) ? { state, group: null } : null
+  }
+  if (!isModifierName(name, slash + 1, name.length)) return null
+  const state = name.slice(groupPrefixLength, slash)
+  return stateModifierSet.has(state) ? { state, group: name.slice(slash + 1) } : null
+}
+
+export interface ContainerModifier {
+  /** the size condition; the registry only accepts a registered media name here */
+  size: string
+  /** the container name, or null for the nearest container */
+  container: string | null
+}
+
+interface ModifierTrieNode {
+  modifiers: readonly string[]
+  children: Map<string, ModifierTrieNode>
+  next?: readonly string[]
+}
+
+/**
+ * Container query modifiers own the `@` prefix: `@sm` targets the nearest
+ * container and `@sm/card` a named one (plan decisions 17-18). Plain `sm:` stays
+ * a viewport media query, which is why the prefix is reserved.
+ *
+ * This parses the spelling only. Whether `size` names a registered media key is
+ * config-dependent, so the registry checks that on lookup and lowering resolves
+ * the query text — the same split groups use for their state part.
+ */
+export function parseContainerModifier(name: string): ContainerModifier | null {
+  if (name.charCodeAt(0) !== 64 /* @ */) return null
+  const slash = name.indexOf('/')
+  if (slash === -1) {
+    return isModifierName(name, 1, name.length)
+      ? { size: name.slice(1), container: null }
+      : null
+  }
+  if (!isModifierName(name, 1, slash) || !isModifierName(name, slash + 1, name.length)) {
+    return null
+  }
+  return { size: name.slice(1, slash), container: name.slice(slash + 1) }
+}
+
+/** the shared identifier rule for the parameterized parts of a modifier */
+function isModifierName(text: string, start: number, end: number): boolean {
+  if (start >= end) return false
+  for (let index = start; index < end; index++) {
+    const code = text.charCodeAt(index)
+    if (
+      !(code >= 97 && code <= 122) && // a-z
+      !(code >= 65 && code <= 90) && // A-Z
+      !(code >= 48 && code <= 57) && // 0-9
+      code !== 45 && // -
+      code !== 95 // _
+    ) {
+      return false
+    }
+  }
+  return true
+}
+
+function forEachName(source: Names | undefined, visit: (name: string) => void): void {
+  if (!source) return
+  if (Array.isArray(source)) {
+    for (const name of source) visit(name)
+    return
+  }
+  if (source instanceof Set) {
+    for (const name of source) visit(name)
+    return
+  }
+  for (const name in source as Readonly<Record<string, unknown>>) visit(name)
+}
+
+export function createModifierRegistry(
+  view: GrammarConfigView,
+  options: CreateModifierRegistryOptions = {}
+): ModifierRegistryResult {
+  const names = new Map<string, ModifierKind>()
+  const diagnostics: string[] = []
+  const completionNames: string[] = []
+
+  // options override the view's derived set. an undefined BOTH falls back to
+  // every-media-name for now — that over-claim is scheduled for removal with
+  // its own caller sweep; views built from media records already carry the
+  // correct derived subset
+  const sizeSource = options.containerSizeNames ?? view.containerSizeNames
+  let containerSizes: Set<string> | null = null
+  if (sizeSource !== undefined) {
+    containerSizes = new Set()
+    forEachName(sizeSource, (name) => containerSizes!.add(name))
+  }
+
+  const register = (name: string, kind: ModifierKind): void => {
+    if (name.charCodeAt(0) === 64 /* @ */) {
+      // the `@` prefix belongs to container queries, so no configured name may
+      // take it; otherwise `@sm:` would mean two things
+      diagnostics.push(
+        `modifier "${name}" is not registered: the "@" prefix is reserved for container query modifiers, so it cannot be a ${kind} name`
+      )
+      return
+    }
+    const existing = names.get(name)
+    if (existing !== undefined) {
+      if (existing !== kind) {
+        diagnostics.push(
+          `modifier "${name}" is already registered as a ${existing} modifier, so the ${kind} name is ignored`
+        )
+      }
+      return
+    }
+    if (parseGroupModifier(name) !== null) {
+      diagnostics.push(
+        `modifier "${name}" shadows the group modifier of the same spelling, which can no longer be used as a ${kind} name`
+      )
+    }
+    names.set(name, kind)
+    completionNames.push(name)
+  }
+
+  // when the caller or the view declares which sizes a container can measure,
+  // that list is the whole rule. Otherwise any registered media name works
+  // (legacy fallback, removal pending its caller sweep)
+  const isContainerSize = (size: string): boolean =>
+    containerSizes ? containerSizes.has(size) : names.get(size) === 'media'
+
+  for (const name of stateModifierNames) register(name, 'state')
+  forEachName(view.mediaNames, (name) => register(name, 'media'))
+  forEachName(view.platformNames ?? grammarPlatformNames, (name) =>
+    register(name, 'platform')
+  )
+  forEachName(view.themeNames, (name) => {
+    if (isRootThemeName(name)) register(name, 'theme')
+  })
+
+  for (const name of stateModifierNames) {
+    const group = `group-${name}`
+    if (names.get(group) === undefined) completionNames.push(group)
+  }
+  if (containerSizes) {
+    for (const size of containerSizes) {
+      if (isContainerSize(size)) completionNames.push(`@${size}`)
+    }
+  } else {
+    for (const name of completionNames.slice()) {
+      if (names.get(name) === 'media') completionNames.push(`@${name}`)
+    }
+  }
+
+  const kindOrder: Readonly<Record<ModifierKind, number>> = {
+    platform: 0,
+    theme: 1,
+    container: 2,
+    media: 3,
+    group: 4,
+    state: 5,
+  }
+  const modifierTrie: ModifierTrieNode = {
+    modifiers: [],
+    children: new Map(),
+  }
+
+  const get = (name: string): ModifierKind | undefined => {
+    const kind = names.get(name)
+    if (kind !== undefined) return kind
+    if (parseGroupModifier(name) !== null) return 'group'
+    const container = parseContainerModifier(name)
+    if (container !== null && isContainerSize(container.size)) return 'container'
+    return undefined
+  }
+
+  return {
+    registry: {
+      get,
+      next(modifiers: readonly string[]): readonly string[] {
+        let node = modifierTrie
+        for (const authored of modifiers) {
+          const canonical = canonicalClauseModifier(authored)
+          let child = node.children.get(canonical)
+          if (!child) {
+            child = {
+              modifiers: [...node.modifiers, canonical],
+              children: new Map(),
+            }
+            node.children.set(canonical, child)
+          }
+          node = child
+        }
+        if (node.next) return node.next
+
+        const used = new Set<string>()
+        const usedKinds = new Set<ModifierKind>()
+        let highestOrder = -1
+        let nonPlatformDepth = 0
+
+        for (const canonical of node.modifiers) {
+          if (used.has(canonical)) {
+            node.next = []
+            return node.next
+          }
+          used.add(canonical)
+          const kind = get(canonical)
+          if (!kind || usedKinds.has(kind) || kindOrder[kind] < highestOrder) {
+            node.next = []
+            return node.next
+          }
+          usedKinds.add(kind)
+          highestOrder = kindOrder[kind]
+          if (kind !== 'platform') {
+            nonPlatformDepth++
+            if (nonPlatformDepth > grammarMaxNonPlatformDepth) {
+              node.next = []
+              return node.next
+            }
+          }
+        }
+
+        const next: string[] = []
+        for (const name of completionNames) {
+          const canonical = canonicalClauseModifier(name)
+          if (canonical !== name) continue
+          if (used.has(canonical)) continue
+          const kind = get(name)
+          if (!kind || kindOrder[kind] < highestOrder) continue
+          if (usedKinds.has(kind)) continue
+          if (kind !== 'platform' && nonPlatformDepth >= grammarMaxNonPlatformDepth) {
+            continue
+          }
+          next.push(name)
+        }
+        node.next = next
+        return node.next
+      },
+    },
+    diagnostics,
+  }
+}

package/src/payloadShape.ts

@@ -0,0 +1,92 @@
+// Value-level payload-shape validation, owned by the resolution layer per the
+// design record ("Value-level validation of resolved payloads has exactly one
+// owner, the resolution step"). One source of truth for the runtime, the
+// compiler, and the ESLint rule — none of them may grow a second opinion
+// about what a suspicious payload looks like.
+//
+// The clause grammar is space-greedy by design: a payload extends until the
+// next `modifier:` clause, because many longhands legitimately take
+// space-separated component lists (`boxShadow="inset 0 2px red"`). The
+// consequence is that a base written AFTER a conditional is absorbed into
+// that conditional's payload — `backgroundColor="sm:green red"` parses as one
+// clause with payload "green red" and NO base, the browser then drops the
+// invalid declaration, and the element renders with nothing at every
+// viewport. The absorption stays (changing it would break legitimate
+// multi-component payloads); the silence goes: a multi-component payload on a
+// longhand that takes exactly one component value is a diagnostic.
+
+import { splitTopLevelComponents } from './backgroundFamily'
+
+/**
+ * Longhands whose value is a component LIST, where a multi-component payload
+ * is ordinary CSS. Everything else that this validator is asked about is
+ * treated as single-component. Family shorthands (`border`, `background`,
+ * `textDecoration`, `font`) never reach payload validation — they split into
+ * per-longhand programs first.
+ */
+const listValuedLonghands: ReadonlySet<string> = new Set([
+  'boxShadow',
+  'textShadow',
+  'transform',
+  'transition',
+  'transitionProperty',
+  'animation',
+  'animationName',
+  'backgroundImage',
+  'backgroundPosition',
+  'backgroundSize',
+  'backgroundRepeat',
+  'fontFamily',
+  'fontVariant',
+  'filter',
+  'backdropFilter',
+  'willChange',
+  'quotes',
+  'textDecorationLine',
+  'containIntrinsicSize',
+  'strokeDasharray',
+  'gridTemplateColumns',
+  'gridTemplateRows',
+  'gridTemplateAreas',
+  'gridArea',
+  'gridColumn',
+  'gridRow',
+  'inset',
+  'mask',
+  'maskImage',
+  'maskPosition',
+  'maskSize',
+])
+
+export interface PayloadShapeDiagnostic {
+  code: 'multi-component-single-value'
+  property: string
+  payload: string
+  message: string
+}
+
+/**
+ * Returns a diagnostic when `payload` holds more than one top-level component
+ * for a longhand that takes exactly one. `hasBase` sharpens the message: with
+ * no base in the program, the most likely cause is a base written after a
+ * conditional and swallowed by its space-greedy payload.
+ */
+export function validatePayloadShape(
+  property: string,
+  payload: string,
+  hasBase: boolean
+): PayloadShapeDiagnostic | null {
+  if (listValuedLonghands.has(property)) return null
+  const components = splitTopLevelComponents(payload)
+  if (components.length <= 1) return null
+  return {
+    code: 'multi-component-single-value',
+    property,
+    payload,
+    message:
+      `"${payload}" holds ${components.length} values but "${property}" takes one.` +
+      (hasBase
+        ? ''
+        : ` A value written after a conditional joins that conditional's payload — write the base value before the first conditional.`),
+  }
+}

package/src/programEligibility.ts

@@ -0,0 +1,46 @@
+// One owner for "does a flat clause value on this prop evaluate through the
+// program engine". The runtime consults it before contributing, the codemod
+// consults it before converting a condition object, and the ESLint rule
+// consults it before blessing a clause spelling — so a migration can never
+// produce source the runtime will not evaluate (review P0-2).
+
+/**
+ * Props with no per-part flat clause spelling BY DESIGN, mapped to the
+ * composite property that owns their clause spelling.
+ *
+ * - RN shadow parts are not CSS longhands: plain values compose into
+ *   boxShadow/textShadow (web `styleToCSS`) or pass straight to the RN host,
+ *   and the composite property carries any conditional.
+ * - Transform parts outside the flat family (skews, 3D rotations,
+ *   perspective, matrix) have no per-part spelling; the raw `transform`
+ *   property is one ordinary program and owns their clauses (design record,
+ *   "The transform family").
+ */
+export const legacyPartComposite: Readonly<Record<string, string>> = Object.freeze({
+  shadowColor: 'boxShadow',
+  shadowOffset: 'boxShadow',
+  shadowOpacity: 'boxShadow',
+  shadowRadius: 'boxShadow',
+  textShadowColor: 'textShadow',
+  textShadowOffset: 'textShadow',
+  textShadowRadius: 'textShadow',
+  perspective: 'transform',
+  skewX: 'transform',
+  skewY: 'transform',
+  matrix: 'transform',
+  rotateX: 'transform',
+  rotateY: 'transform',
+  rotateZ: 'transform',
+})
+
+export type ProgramEligibility = 'program' | 'legacy-part'
+
+/**
+ * 'program': a clause-bearing flat value on this prop evaluates through the
+ * program engine. 'legacy-part': plain values keep their legacy pipeline and
+ * a clause-bearing value is a diagnostic naming the composite — never a
+ * silent forward, never a codemod conversion.
+ */
+export function programEligibility(prop: string): ProgramEligibility {
+  return prop in legacyPartComposite ? 'legacy-part' : 'program'
+}

package/src/programHash.ts

@@ -0,0 +1,128 @@
+// Deterministic identity for one lowered program.
+//
+// A (longhand property, program, config revision) triple hashes to one class
+// name, which is the whole dedup mechanism for the program block encoding: a
+// class name fully determines its block, so duplicate arrival is idempotent and
+// dedup is a name check. See plans/dom-tailwind-flat-values.md — "The program
+// block encoding".
+//
+// Server and client must agree, so nothing here may depend on iteration order,
+// config object identity, or insertion history. The config revision is the
+// caller's opaque stamp for "the resolved config that produced these payloads".
+
+import { canonicalClauseModifier } from './clausePrecedence'
+import type { ParsedValue } from './valueTypes'
+
+// The hash is the algorithm from @tamagui/simple-hash
+// (code/core/simple-hash/src/index.ts), copied rather than imported because this
+// package stays dependency-free. Same accumulator, same CSS-safe character
+// rules, so identifiers behave like the ones core already generates. Keep in
+// sync if that file changes. Two deliberate differences: no memo cache (callers
+// own caching, and a shared module-level cache in the grammar package would
+// outlive every config), and `strict` mode at the call site below.
+function hashChar(hash: number, char: string): number {
+  return (Math.imul(31, hash) + char.charCodeAt(0)) | 0
+}
+
+function isValidCssCharCode(code: number): boolean {
+  return (
+    (code >= 65 && code <= 90) || // A-Z
+    (code >= 97 && code <= 122) || // a-z
+    code === 95 || // _
+    code === 45 || // -
+    (code >= 48 && code <= 57) // 0-9
+  )
+}
+
+function simpleHash(input: string, hashMin: number | 'strict' = 10): string {
+  let str = input
+
+  // remove var()
+  if (str[0] === 'v' && str.startsWith('var(')) {
+    str = str.slice(6, str.length - 1)
+  }
+
+  let hash = 0
+  let valids = ''
+  let added = 0
+  const len = str.length
+
+  for (let i = 0; i < len; i++) {
+    if (hashMin !== 'strict' && added <= hashMin) {
+      const char = str.charCodeAt(i)
+      if (char === 46) {
+        valids += '--'
+        continue
+      }
+      if (isValidCssCharCode(char)) {
+        added++
+        valids += str[i]
+        continue
+      }
+    }
+    hash = hashChar(hash, str[i])
+  }
+
+  return valids + (hash ? Math.abs(hash) : '')
+}
+
+/**
+ * The exact string that identifies a program. Every variable-length part is
+ * length-prefixed, so no payload can forge a boundary and two different
+ * programs cannot normalize to the same key. Also usable as the upstream
+ * parse/lower cache key.
+ */
+export function normalizeProgramKey(
+  property: string,
+  value: ParsedValue,
+  configRevision: string
+): string {
+  let key = `${configRevision.length}:${configRevision}${property.length}:${property}`
+  key += value.base === null ? 'n' : `b${value.base.length}:${value.base}`
+  for (const clause of value.clauses) {
+    // condition sets are conjunctions: `dark:hover:` and `hover:dark:` are one
+    // clause, so the hash sorts a copy to agree with the merge rule and dedup;
+    // alias spellings canonicalize first so `active:` and `press:` are one name
+    const canonical = clause.modifiers.map(canonicalClauseModifier)
+    const modifiers =
+      canonical.length > 1 ? canonical.sort().join(',') : canonical.join(',')
+    key += `c${modifiers.length}:${modifiers}${clause.payload.length}:${clause.payload}`
+  }
+  return key
+}
+
+/**
+ * Short per-property prefix for readability in devtools: the first letter of
+ * each camelCase word, so `backgroundColor` is `bc` and `borderTopLeftRadius`
+ * is `btlr`. Abbreviations may collide (`backgroundColor` and `backgroundClip`
+ * are both `bc`); the hash carries the property name, so the full class name
+ * still differs. This is a label, not identity.
+ */
+export function propertyAbbreviation(property: string): string {
+  let out = ''
+  for (let index = 0; index < property.length; index++) {
+    const code = property.charCodeAt(index)
+    const isWordStart =
+      index === 0 ||
+      (code >= 65 && code <= 90) ||
+      // a dash also starts a word, so the transform family's custom properties
+      // read as `--t-x` -> `tx` rather than collapsing to the fallback
+      property.charCodeAt(index - 1) === 45
+    if (isWordStart && ((code >= 65 && code <= 90) || (code >= 97 && code <= 122))) {
+      out += property[index].toLowerCase()
+    }
+  }
+  return out || 'x'
+}
+
+/** the css-safe class name that owns this program's block, eg `_bc-1076745300` */
+export function programClassName(
+  property: string,
+  value: ParsedValue,
+  configRevision: string
+): string {
+  const hash = simpleHash(normalizeProgramKey(property, value, configRevision), 'strict')
+  // `strict` returns '' when the accumulator lands on 0, which would make every
+  // such program share one name
+  return `_${propertyAbbreviation(property)}-${hash || '0'}`
+}