tjs-lang 0.8.7 → 0.9.0

package/src/css/css.test.ts

@@ -0,0 +1,122 @@
+/**
+ * `tjs-lang/css` phase 1 — the color grammar. Proves the full vertical slice:
+ * the predicate source verifies safe (pure + ReDoS-clean), compiles to correct
+ * native validators, and mines valid autocomplete suggestions.
+ */
+import { describe, it, expect } from 'bun:test'
+import {
+  isColor,
+  isColorValue,
+  isNamedColor,
+  isHexColor,
+  verifyCss,
+  suggestColor,
+  CSS_NAMED_COLORS,
+} from './index'
+
+describe('CSS color source is predicate-safe', () => {
+  it('verifies pure, synchronous, ReDoS-clean', () => {
+    const r = verifyCss()
+    if (!r.safe) console.error(r.diagnostics)
+    expect(r.safe).toBe(true)
+    expect(r.diagnostics).toEqual([])
+  })
+})
+
+describe('isColor accepts valid CSS colors', () => {
+  const valid = [
+    'red',
+    'REBECCAPURPLE', // case-insensitive named
+    'transparent',
+    'currentColor',
+    '#f00',
+    '#ff0000',
+    '#ff0000aa', // 8-digit
+    '#abcd', // 4-digit
+    'rgb(255, 0, 0)',
+    'rgb(255 0 0 / 0.5)', // modern slash syntax
+    'rgba(0,0,0,0.2)',
+    'hsl(120, 50%, 50%)',
+    'hsl(120deg 50% 50% / 0.5)',
+    'hwb(194 0% 0%)',
+    'oklch(0.7 0.15 200)',
+    'lab(50% 40 59.5)',
+    'color-mix(in oklch, red, blue)',
+    'color(display-p3 1 0.5 0)',
+    'var(--brand)',
+  ]
+  for (const c of valid) {
+    it(`accepts ${c}`, () => expect(isColor(c)).toBe(true))
+  }
+})
+
+describe('isColor rejects non-colors', () => {
+  const invalid = [
+    'notacolor',
+    '#gg0000', // non-hex digits
+    '#12345', // 5 digits (not 3/4/6/8)
+    'reddish',
+    '',
+    'rgb', // no parens
+    'linear-gradient(red, blue)', // a gradient, not a color
+    42,
+    null,
+    undefined,
+    {},
+  ]
+  for (const c of invalid) {
+    it(`rejects ${JSON.stringify(c)}`, () => expect(isColor(c)).toBe(false))
+  }
+})
+
+describe('isColorValue tolerates !important', () => {
+  it('accepts a color with !important', () => {
+    expect(isColorValue('#3a3 !important')).toBe(true)
+    expect(isColorValue('red !important')).toBe(true)
+  })
+  it('still rejects a non-color with !important', () => {
+    expect(isColorValue('notacolor !important')).toBe(false)
+  })
+  it('isColor (strict) does not accept !important', () => {
+    expect(isColor('red !important')).toBe(false)
+  })
+})
+
+describe('leaf predicates', () => {
+  it('isNamedColor is case-insensitive and complete-ish', () => {
+    expect(isNamedColor('RebeccaPurple')).toBe(true)
+    expect(isNamedColor('cornflowerblue')).toBe(true)
+    expect(isNamedColor('bluish')).toBe(false)
+    // sanity: the full named set is present
+    expect(CSS_NAMED_COLORS.length).toBeGreaterThan(140)
+  })
+  it('isHexColor validates digit counts', () => {
+    expect(isHexColor('#abc')).toBe(true)
+    expect(isHexColor('#abcd')).toBe(true)
+    expect(isHexColor('#aabbcc')).toBe(true)
+    expect(isHexColor('#aabbccdd')).toBe(true)
+    expect(isHexColor('#ab')).toBe(false)
+    expect(isHexColor('#abcde')).toBe(false)
+  })
+})
+
+describe('suggestColor mines valid completions', () => {
+  it('suggests named colors for a prefix, all valid', () => {
+    const s = suggestColor('red')
+    const values = s.filter((x) => x.kind === 'value').map((x) => x.value)
+    expect(values).toContain('red')
+    // every suggested value actually passes the predicate (mined + validated)
+    for (const v of values) expect(isColor(v)).toBe(true)
+  })
+  it('offers the open var(-- stub for a relevant prefix', () => {
+    // Empty-prefix suggest floods with named colors (correctly); autocomplete is
+    // prefix-driven, so the open functional stubs surface once you start typing.
+    const s = suggestColor('var')
+    const stubs = s.filter((x) => x.kind === 'stub').map((x) => x.value)
+    expect(stubs).toContain('var(--')
+  })
+  it('offers color-mix( for the color- prefix', () => {
+    const s = suggestColor('color-')
+    expect(s.some((x) => x.value === 'color-mix(')).toBe(true)
+  })
+})

package/src/css/dimensions.test.ts

@@ -0,0 +1,112 @@
+/**
+ * `tjs-lang/css` phase 2 — dimensions / numbers / angles / times / keywords.
+ * Same vertical slice as colors: the source verifies safe (via `verifyCss`,
+ * which now covers all clusters) and compiles to correct native validators.
+ */
+import { describe, it, expect } from 'bun:test'
+import {
+  isLength,
+  isPercentage,
+  isNumber,
+  isInteger,
+  isAngle,
+  isTime,
+  isDimension,
+  isGlobalKeyword,
+  verifyCss,
+} from './index'
+
+describe('all CSS clusters are predicate-safe (incl. dimensions)', () => {
+  it('verifyCss covers color + dimension, all safe', () => {
+    const r = verifyCss()
+    if (!r.safe) console.error(r.diagnostics)
+    expect(r.safe).toBe(true)
+  })
+})
+
+describe('isLength', () => {
+  const valid = [
+    '0', // unitless zero
+    '10px',
+    '1.5rem',
+    '-2em',
+    '100vh',
+    '50vmax',
+    '3ch',
+    '2.5cqw', // container query unit
+    '1dvh', // dynamic viewport
+    '10Q',
+    '.5in',
+    'calc(100% - 10px)',
+    'var(--gap)',
+  ]
+  for (const v of valid)
+    it(`accepts ${v}`, () => expect(isLength(v)).toBe(true))
+
+  const invalid = ['10', '10foo', 'px', '10 px', 'red', '', {}, null]
+  for (const v of invalid)
+    it(`rejects ${JSON.stringify(v)}`, () => expect(isLength(v)).toBe(false))
+
+  it('accepts numeric 0 (unitless zero) but not other bare numbers', () => {
+    expect(isLength(0)).toBe(true)
+    expect(isLength(10)).toBe(false) // a bare number isn't a length
+  })
+})
+
+describe('isPercentage', () => {
+  it('accepts', () => {
+    expect(isPercentage('50%')).toBe(true)
+    expect(isPercentage('-12.5%')).toBe(true)
+  })
+  it('rejects', () => {
+    expect(isPercentage('50')).toBe(false)
+    expect(isPercentage('50px')).toBe(false)
+  })
+})
+
+describe('isNumber / isInteger', () => {
+  it('isNumber accepts numbers and numeric strings', () => {
+    expect(isNumber(42)).toBe(true)
+    expect(isNumber(3.14)).toBe(true)
+    expect(isNumber('42')).toBe(true)
+    expect(isNumber('-.5')).toBe(true)
+    expect(isNumber('4px')).toBe(false)
+    expect(isNumber(Infinity)).toBe(false)
+    expect(isNumber(NaN)).toBe(false)
+  })
+  it('isInteger', () => {
+    expect(isInteger(5)).toBe(true)
+    expect(isInteger('5')).toBe(true)
+    expect(isInteger(5.5)).toBe(false)
+    expect(isInteger('5.0')).toBe(false)
+  })
+})
+
+describe('isAngle / isTime', () => {
+  it('angles', () => {
+    for (const a of ['45deg', '1turn', '1.5rad', '100grad', '-90deg'])
+      expect(isAngle(a)).toBe(true)
+    expect(isAngle('45')).toBe(false)
+    expect(isAngle('45px')).toBe(false)
+  })
+  it('times', () => {
+    expect(isTime('200ms')).toBe(true)
+    expect(isTime('1s')).toBe(true)
+    expect(isTime('1.5s')).toBe(true)
+    expect(isTime('1')).toBe(false)
+  })
+})
+
+describe('isDimension (any numeric family) + isGlobalKeyword', () => {
+  it('isDimension unifies the families', () => {
+    for (const v of ['10px', '50%', '45deg', '1s', '42', 'calc(1px + 2px)'])
+      expect(isDimension(v)).toBe(true)
+    expect(isDimension('red')).toBe(false)
+  })
+  it('isGlobalKeyword', () => {
+    for (const k of ['inherit', 'initial', 'unset', 'revert', 'revert-layer'])
+      expect(isGlobalKeyword(k)).toBe(true)
+    expect(isGlobalKeyword('INHERIT')).toBe(true) // case-insensitive
+    expect(isGlobalKeyword('auto')).toBe(false)
+  })
+})

package/src/css/dimensions.ts

@@ -0,0 +1,146 @@
+/**
+ * CSS dimension / numeric value grammar (phase 2) — the other big family of leaf
+ * values: lengths, percentages, angles, times, resolutions, plain numbers, and
+ * the CSS-wide global keywords. Same rules as the color cluster: pure,
+ * synchronous, ReDoS-clean (flat character classes / bounded alternation only),
+ * with `var(--…)`/`calc(…)` as the open escapes.
+ *
+ * The numeric core `[+-]?(\d*\.\d+|\d+)` is a bounded alternation (each branch a
+ * single quantifier — no nesting), so it passes the verifier's ReDoS lint.
+ */
+
+/** Absolute + relative + container + viewport length units (CSS Values 4). */
+export const CSS_LENGTH_UNITS = [
+  // font-relative
+  'cap',
+  'ch',
+  'em',
+  'ex',
+  'ic',
+  'lh',
+  'rcap',
+  'rch',
+  'rem',
+  'rex',
+  'ric',
+  'rlh',
+  // viewport
+  'vw',
+  'vh',
+  'vi',
+  'vb',
+  'vmin',
+  'vmax',
+  'svw',
+  'svh',
+  'svi',
+  'svb',
+  'svmin',
+  'svmax',
+  'lvw',
+  'lvh',
+  'lvi',
+  'lvb',
+  'lvmin',
+  'lvmax',
+  'dvw',
+  'dvh',
+  'dvi',
+  'dvb',
+  'dvmin',
+  'dvmax',
+  // container query
+  'cqw',
+  'cqh',
+  'cqi',
+  'cqb',
+  'cqmin',
+  'cqmax',
+  // absolute
+  'px',
+  'cm',
+  'mm',
+  'q',
+  'in',
+  'pt',
+  'pc',
+]
+
+/** CSS-wide keywords valid on any property. */
+export const CSS_GLOBAL_KEYWORDS = [
+  'inherit',
+  'initial',
+  'unset',
+  'revert',
+  'revert-layer',
+]
+
+/**
+ * Dimension predicate cluster (source). Entry points cover each numeric family
+ * plus `isDimension` (any of them) and `isGlobalKeyword`. Units are ordered
+ * longest-first inside the alternation so e.g. `rem` isn't shadowed by `em`
+ * (belt-and-suspenders — the `$` anchor already forces a full match).
+ */
+export const CSS_DIMENSION_SOURCE = `
+var CSS_LENGTH_UNITS = ${JSON.stringify(
+  // longest-first for safe alternation ordering
+  [...CSS_LENGTH_UNITS].sort((a, b) => b.length - a.length)
+)}
+var CSS_GLOBAL_KEYWORDS = ${JSON.stringify(CSS_GLOBAL_KEYWORDS)}
+
+function isCssVar(v) {
+  return typeof v === 'string' && v.startsWith('var(--') && v.endsWith(')')
+}
+function isCssCalc(v) {
+  return typeof v === 'string' && v.startsWith('calc(') && v.endsWith(')')
+}
+function isNumber(v) {
+  if (typeof v === 'number') { return isFinite(v) }
+  return typeof v === 'string' && /^[+-]?(\\d*\\.\\d+|\\d+)$/.test(v)
+}
+function isInteger(v) {
+  if (typeof v === 'number') { return Number.isInteger(v) }
+  return typeof v === 'string' && /^[+-]?\\d+$/.test(v)
+}
+function isPercentage(v) {
+  return typeof v === 'string' && /^[+-]?(\\d*\\.\\d+|\\d+)%$/.test(v)
+}
+function isLength(v) {
+  if (v === 0 || v === '0') { return true }
+  if (isCssVar(v) || isCssCalc(v)) { return true }
+  if (typeof v !== 'string') { return false }
+  var m = v.match(/^[+-]?(\\d*\\.\\d+|\\d+)([a-z%]+)$/i)
+  if (m === null) { return false }
+  return CSS_LENGTH_UNITS.includes(m[2].toLowerCase())
+}
+function isAngle(v) {
+  return typeof v === 'string' && /^[+-]?(\\d*\\.\\d+|\\d+)(deg|grad|rad|turn)$/i.test(v)
+}
+function isTime(v) {
+  return typeof v === 'string' && /^[+-]?(\\d*\\.\\d+|\\d+)(ms|s)$/i.test(v)
+}
+function isResolution(v) {
+  return typeof v === 'string' && /^[+-]?(\\d*\\.\\d+|\\d+)(dpi|dpcm|dppx|x)$/i.test(v)
+}
+function isGlobalKeyword(v) {
+  return typeof v === 'string' && CSS_GLOBAL_KEYWORDS.includes(v.toLowerCase())
+}
+function isDimension(v) {
+  return isLength(v) || isPercentage(v) || isAngle(v)
+      || isTime(v) || isResolution(v) || isNumber(v)
+      || isCssVar(v) || isCssCalc(v)
+}
+`
+
+/** Entry predicates exported by the dimension cluster (for compile/suggest). */
+export const CSS_DIMENSION_ENTRIES = [
+  'isNumber',
+  'isInteger',
+  'isPercentage',
+  'isLength',
+  'isAngle',
+  'isTime',
+  'isResolution',
+  'isGlobalKeyword',
+  'isDimension',
+] as const

package/src/css/index.ts

@@ -0,0 +1,243 @@
+/**
+ * `tjs-lang/css` — CSS validation built from verified-safe predicates.
+ *
+ * The "computational half" of a CSS schema: precise, total validators for the
+ * open value grammars TS/JSON-Schema cave to `string` on (colors here in
+ * phase 1; lengths, shorthands and the recursive style-object structure land in
+ * later phases — see TODO.md #4). Every validator is compiled from a
+ * predicate-safe source cluster (`./predicates`), so it is pure, synchronous,
+ * fuel-bounded, and ReDoS-clean — safe to run on untrusted input.
+ *
+ * Autocomplete rides the same source: `suggestColor()` mines the named-color set
+ * and the open functional stubs (`var(--`, `color-mix(`, …), validating mined
+ * values through the compiled predicate so completions are guaranteed valid.
+ */
+import {
+  compilePredicate,
+  verifyPredicate,
+  suggest,
+  type PredicateVerifyResult,
+  type Suggestion,
+} from '../lang/predicate'
+import {
+  CSS_COLOR_SOURCE,
+  CSS_COLOR_ENTRIES,
+  CSS_NAMED_COLORS,
+} from './predicates'
+import {
+  CSS_DIMENSION_SOURCE,
+  CSS_DIMENSION_ENTRIES,
+  CSS_LENGTH_UNITS,
+  CSS_GLOBAL_KEYWORDS,
+} from './dimensions'
+import { CSS_STYLE_SOURCE, CSS_STYLE_ENTRIES } from './style'
+import { CSS_SHORTHAND_SOURCE, CSS_SHORTHAND_ENTRIES } from './shorthands'
+
+export {
+  CSS_COLOR_SOURCE,
+  CSS_COLOR_ENTRIES,
+  CSS_NAMED_COLORS,
+} from './predicates'
+export {
+  CSS_DIMENSION_SOURCE,
+  CSS_DIMENSION_ENTRIES,
+  CSS_LENGTH_UNITS,
+  CSS_GLOBAL_KEYWORDS,
+} from './dimensions'
+export {
+  CSS_STYLE_SOURCE,
+  CSS_STYLE_ENTRIES,
+  cssStyleSchema,
+  cssColorSchema,
+  cssDimensionSchema,
+} from './style'
+export {
+  CSS_SHORTHAND_SOURCE,
+  CSS_SHORTHAND_ENTRIES,
+  cssAnimationSchema,
+  cssTransitionSchema,
+} from './shorthands'
+
+/** Every predicate-source cluster the library ships, keyed for verify/drift. */
+const CSS_SOURCES: Record<string, string> = {
+  color: CSS_COLOR_SOURCE,
+  dimension: CSS_DIMENSION_SOURCE,
+  style: CSS_STYLE_SOURCE,
+  shorthand: CSS_SHORTHAND_SOURCE,
+}
+
+type ColorValidators = Record<
+  (typeof CSS_COLOR_ENTRIES)[number],
+  (v: unknown) => boolean
+>
+type DimensionValidators = Record<
+  (typeof CSS_DIMENSION_ENTRIES)[number],
+  (v: unknown) => boolean
+>
+
+// Compiled once, on first use (verification + `new Function` are one-time).
+let _color: ColorValidators | null = null
+function colorValidators(): ColorValidators {
+  if (!_color) {
+    _color = compilePredicate(
+      CSS_COLOR_SOURCE,
+      CSS_COLOR_ENTRIES as unknown as string[]
+    ) as ColorValidators
+  }
+  return _color
+}
+
+let _dimension: DimensionValidators | null = null
+function dimensionValidators(): DimensionValidators {
+  if (!_dimension) {
+    _dimension = compilePredicate(
+      CSS_DIMENSION_SOURCE,
+      CSS_DIMENSION_ENTRIES as unknown as string[]
+    ) as DimensionValidators
+  }
+  return _dimension
+}
+
+type StyleValidators = Record<
+  (typeof CSS_STYLE_ENTRIES)[number],
+  (v: unknown) => boolean
+>
+let _style: StyleValidators | null = null
+function styleValidators(): StyleValidators {
+  if (!_style) {
+    _style = compilePredicate(
+      CSS_STYLE_SOURCE,
+      CSS_STYLE_ENTRIES as unknown as string[]
+    ) as StyleValidators
+  }
+  return _style
+}
+
+type ShorthandValidators = Record<
+  (typeof CSS_SHORTHAND_ENTRIES)[number],
+  (v: unknown) => boolean
+>
+let _shorthand: ShorthandValidators | null = null
+function shorthandValidators(): ShorthandValidators {
+  if (!_shorthand) {
+    _shorthand = compilePredicate(
+      CSS_SHORTHAND_SOURCE,
+      CSS_SHORTHAND_ENTRIES as unknown as string[]
+    ) as ShorthandValidators
+  }
+  return _shorthand
+}
+
+/** Is `v` a valid CSS color (named, hex, rgb/hsl, modern fn, or `var(--…)`)? */
+export const isColor = (v: unknown): boolean => colorValidators().isColor(v)
+/** Like {@link isColor}, but tolerates a trailing `!important`. */
+export const isColorValue = (v: unknown): boolean =>
+  colorValidators().isColorValue(v)
+/** Is `v` a CSS named color (incl. `transparent`/`currentcolor`)? */
+export const isNamedColor = (v: unknown): boolean =>
+  colorValidators().isNamedColor(v)
+/** Is `v` a CSS hex color (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`)? */
+export const isHexColor = (v: unknown): boolean =>
+  colorValidators().isHexColor(v)
+
+// --- dimensions / numbers / keywords (phase 2) ------------------------------
+
+/** Is `v` a CSS `<length>` (unit'd, unitless `0`, or `var()`/`calc()`)? */
+export const isLength = (v: unknown): boolean =>
+  dimensionValidators().isLength(v)
+/** Is `v` a CSS `<percentage>` (`50%`)? */
+export const isPercentage = (v: unknown): boolean =>
+  dimensionValidators().isPercentage(v)
+/** Is `v` a CSS `<number>` (numeric, or a numeric string)? */
+export const isNumber = (v: unknown): boolean =>
+  dimensionValidators().isNumber(v)
+/** Is `v` a CSS `<integer>`? */
+export const isInteger = (v: unknown): boolean =>
+  dimensionValidators().isInteger(v)
+/** Is `v` a CSS `<angle>` (`45deg`, `1turn`, `1.5rad`, `100grad`)? */
+export const isAngle = (v: unknown): boolean => dimensionValidators().isAngle(v)
+/** Is `v` a CSS `<time>` (`200ms`, `1s`)? */
+export const isTime = (v: unknown): boolean => dimensionValidators().isTime(v)
+/** Is `v` any CSS dimension/number (length, %, angle, time, resolution, number)? */
+export const isDimension = (v: unknown): boolean =>
+  dimensionValidators().isDimension(v)
+/** Is `v` a CSS-wide keyword (`inherit`/`initial`/`unset`/`revert`/`revert-layer`)? */
+export const isGlobalKeyword = (v: unknown): boolean =>
+  dimensionValidators().isGlobalKeyword(v)
+
+// --- recursive style-object structure (phase 4) -----------------------------
+
+/**
+ * Is `v` a valid CSS **style object** — an open, recursive map of CSS properties
+ * to values and selectors/at-rules to nested style objects? Validates the whole
+ * structure (keys are properties or selectors; property values are style values,
+ * selector values are nested rules), recursively and fuel-bounded. This is the
+ * shape TS/JSON-Schema can't express.
+ */
+export const isStyleObject = (v: unknown): boolean =>
+  styleValidators().isStyleObject(v)
+/** Is `v` a valid leaf CSS value (a known color/dimension/keyword, else a non-empty string / finite number)? */
+export const isStyleValue = (v: unknown): boolean =>
+  styleValidators().isStyleValue(v)
+/**
+ * Property-AWARE leaf check: given the property name, tightens the closed value
+ * grammars (color/animation/transition) so `isStyleValueFor('color', 'notacolor')`
+ * is `false` while `isStyleValueFor('padding', 'anything')` stays permissive.
+ * This is what makes {@link isStyleObject} catch real value errors.
+ */
+export const isStyleValueFor = (prop: unknown, val: unknown): boolean =>
+  (styleValidators().isStyleValueFor as (p: unknown, v: unknown) => boolean)(
+    prop,
+    val
+  )
+/** Is `k` a CSS property name (`color`, `--custom`, `-webkit-foo`)? */
+export const isCssProperty = (k: unknown): boolean =>
+  styleValidators().isCssProperty(k)
+/** Is `k` a selector or at-rule key (nests a rule) rather than a property? */
+export const isSelectorOrAtRule = (k: unknown): boolean =>
+  styleValidators().isSelectorOrAtRule(k)
+
+// --- order-flexible shorthands (phase 3) ------------------------------------
+
+/** Is `v` a valid CSS `animation` shorthand (comma-separated, order-free tokens)? */
+export const isAnimation = (v: unknown): boolean =>
+  shorthandValidators().isAnimation(v)
+/** Is `v` a valid CSS `transition` shorthand (comma-separated layers)? */
+export const isTransition = (v: unknown): boolean =>
+  shorthandValidators().isTransition(v)
+/** Is `v` a CSS `<easing-function>` (keyword, `cubic-bezier(…)`, `steps(…)`, `linear(…)`)? */
+export const isTimingFunction = (v: unknown): boolean =>
+  shorthandValidators().isTimingFunction(v)
+
+/**
+ * Verify every CSS predicate-source cluster is predicate-safe (pure,
+ * synchronous, ReDoS-clean). Returns the combined result (safe iff all clusters
+ * are; diagnostics carry the cluster name). Always safe for the shipped source —
+ * exposed so downstream tools (and the drift test) can assert it, and so a
+ * consumer embedding a source in a `$predicate` schema can re-check before
+ * trusting it.
+ */
+export function verifyCss(): PredicateVerifyResult {
+  const predicates: string[] = []
+  const diagnostics: PredicateVerifyResult['diagnostics'] = []
+  for (const [name, source] of Object.entries(CSS_SOURCES)) {
+    const r = verifyPredicate(source)
+    predicates.push(...r.predicates)
+    for (const d of r.diagnostics)
+      diagnostics.push({ ...d, predicate: `${name}:${d.predicate}` })
+  }
+  return { safe: diagnostics.length === 0, predicates, diagnostics }
+}
+
+/**
+ * Autocomplete candidates for a CSS color value. Returns concrete named colors
+ * (validated through the compiled predicate) plus open-ended stubs mined from
+ * the functional forms (`var(--`, `color-mix(`, `oklch(`, …). Prefix-filtered.
+ */
+export function suggestColor(prefix = '', limit = 50): Suggestion[] {
+  return suggest(CSS_COLOR_SOURCE, {
+    entry: 'isColor',
+    prefix,
+    limit,
+  })
+}