@ui0/theme 0.0.0-stage → 0.1.0

package/src/contracts/color/color.serialize.spec.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest'
+
+import { hashClassName } from '../../generator/hash'
+import { resolveClass, serializeTokens } from './color.serialize'
+import type { ColorToken } from './color.types'
+
+describe('serializeTokens', () => {
+  it('maps a bare token to the swatch setter', () => {
+    expect(serializeTokens([{ ref: 'error' }], 'c')).toEqual({
+      classes: [hashClassName('c-error')],
+      styles: {}
+    })
+  })
+
+  it('maps scheme, pseudo and opacity onto the class name and inline vars', () => {
+    const tokens: ColorToken[] = [{ scheme: 'dark', pseudo: 'hover', ref: 'warning', opacity: 0.9 }]
+    expect(serializeTokens(tokens, 'c')).toEqual({
+      classes: [hashClassName('dark-hover-c-warning')],
+      styles: { '--0-c-src-d-hover': '0.9' }
+    })
+  })
+
+  it('delivers a plain opacity as an ungated inline source var', () => {
+    expect(serializeTokens([{ ref: 'error', opacity: 0.4 }], 'c')).toEqual({
+      classes: [hashClassName('c-error')],
+      styles: { '--0-c-src': '0.4' }
+    })
+  })
+
+  it('keeps every context on its own source var', () => {
+    const tokens: ColorToken[] = [
+      { ref: 'error', opacity: 0.5 },
+      { scheme: 'light', ref: 'error', opacity: 0.8 },
+      { pseudo: 'focus', ref: 'error', opacity: 0.6 }
+    ]
+    expect(serializeTokens(tokens, 'f')).toEqual({
+      classes: [hashClassName('f-error'), hashClassName('light-f-error'), hashClassName('focus-f-error')],
+      styles: {
+        '--0-f-src': '0.5',
+        '--0-f-src-l': '0.8',
+        '--0-f-src-focus': '0.6'
+      }
+    })
+  })
+
+  it('full opacity emits nothing extra', () => {
+    expect(serializeTokens([{ ref: 'error', opacity: 1 }], 'f')).toEqual({
+      classes: [hashClassName('f-error')],
+      styles: {}
+    })
+  })
+
+  it('resolveClass prefers the module map, hashes otherwise', () => {
+    expect(resolveClass('c-error', { 'c-error': 'x_1' })).toBe('x_1')
+    expect(resolveClass('c-error', {})).toBe(hashClassName('c-error'))
+  })
+})

package/src/contracts/color/color.serialize.ts

@@ -0,0 +1,35 @@
+// tokens -> paint. A token's color selection always compiles to a hashed
+// swatch setter class (`[scheme-][pseudo-]{c|f}-<ref>`) - selections are
+// conditional by nature. Opacity VALUES always ride element inline styles as
+// context source vars (`--0-{slot}-src[-{l|d}][-{pseudo}]`); the conditional
+// pick happens in the component's color.use() scss bridges, so the generated
+// theme css carries no opacity rules at all.
+import type { ClassList, CSSModuleClassList, StyleList } from '@ui0/types'
+
+import { hashClassName } from '../../generator/hash'
+import type { ColorToken } from './color.types'
+
+export function resolveClass(full: string, $?: CSSModuleClassList): string {
+  return ($ && $[full]) || hashClassName(full)
+}
+
+export function serializeTokens(
+  tokens: ColorToken[],
+  slot: 'c' | 'f',
+  $?: CSSModuleClassList
+): { classes: ClassList; styles: StyleList } {
+  const classes: ClassList = []
+  const styles: StyleList = {}
+  const ns = slot === 'c' ? '--0-c' : '--0-f'
+
+  for (const t of tokens) {
+    const pre = `${t.scheme ? t.scheme + '-' : ''}${t.pseudo ? t.pseudo + '-' : ''}${slot}`
+    classes.push(resolveClass(`${pre}-${t.ref}`, $))
+
+    if (t.opacity !== undefined && t.opacity < 1) {
+      const ctx = `${t.scheme === 'light' ? '-l' : t.scheme === 'dark' ? '-d' : ''}${t.pseudo ? `-${t.pseudo}` : ''}`
+      styles[`${ns}-src${ctx}`] = `${t.opacity}`
+    }
+  }
+  return { classes, styles }
+}

package/src/contracts/color/color.token.spec.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest'
+
+import { parseColorProp, parseRef } from './color.token'
+
+describe('parseColorProp - token grammar', () => {
+  it('parses a bare ref for both schemes', () => {
+    expect(parseColorProp('success')).toEqual([{ ref: 'success' }])
+  })
+
+  it('parses ramp refs and opacity via @', () => {
+    expect(parseColorProp('brand-l3@50')).toEqual([{ ref: 'brand-l3', opacity: 0.5 }])
+  })
+
+  it('parses a positional light/dark pair with per-scheme opacity', () => {
+    expect(parseColorProp('success@80/warning@100')).toEqual([
+      { scheme: 'light', ref: 'success', opacity: 0.8 },
+      { scheme: 'dark', ref: 'warning', opacity: 1 }
+    ])
+  })
+
+  it('parses named scheme and pseudo prefixes, order-independent', () => {
+    expect(parseColorProp('dark:warning')).toEqual([{ scheme: 'dark', ref: 'warning' }])
+    expect(parseColorProp('hover:success@90')).toEqual([{ pseudo: 'hover', ref: 'success', opacity: 0.9 }])
+    expect(parseColorProp('dark:hover:warning')).toEqual([{ scheme: 'dark', pseudo: 'hover', ref: 'warning' }])
+    expect(parseColorProp('hover:dark:warning')).toEqual([{ scheme: 'dark', pseudo: 'hover', ref: 'warning' }])
+  })
+
+  it('parses space-separated layers: base + pseudo override', () => {
+    expect(parseColorProp('success hover:warning')).toEqual([{ ref: 'success' }, { pseudo: 'hover', ref: 'warning' }])
+  })
+
+  it('rejects half pairs (single scheme is spelled dark:ref)', () => {
+    expect(() => parseColorProp('/warning')).toThrow()
+    expect(() => parseColorProp('warning/')).toThrow()
+    expect(() => parseColorProp('a/b/c')).toThrow()
+  })
+
+  it('rejects prefixed tokens inside a positional pair', () => {
+    expect(() => parseColorProp('black@50/hover:warning')).toThrow()
+    expect(() => parseColorProp('light:black/warning')).toThrow()
+  })
+
+  it('rejects mixing a positional pair with named schemes', () => {
+    expect(() => parseColorProp('success/warning dark:highlight')).toThrow()
+  })
+
+  it('rejects unknown prefixes and bad opacity', () => {
+    expect(() => parseColorProp('hove:success')).toThrow()
+    expect(() => parseColorProp('success@120')).toThrow()
+    expect(() => parseColorProp('success@abc')).toThrow()
+    expect(() => parseColorProp('hover:')).toThrow()
+  })
+
+  it('parseRef keeps names without @ untouched', () => {
+    expect(parseRef('my-brand-2')).toEqual({ ref: 'my-brand-2' })
+  })
+})

package/src/contracts/color/color.token.ts

@@ -0,0 +1,89 @@
+// The color/fill prop-dsl parser (v2 grammar):
+//
+//   prop  := token (' ' token)*                     tokens = layers: base + overrides
+//   token := ref                     -> both schemes, no pseudo
+//          | ref '/' ref             -> positional pair: light / dark
+//          | [scheme ':'][pseudo ':'] ref
+//   ref   := name ['-' ramp] ['@' pct]
+//
+// examples:
+//   success            both schemes
+//   success@80/warning@100   light success@80, dark warning@100
+//   dark:warning       dark only (light falls back to the inherited/current)
+//   success hover:success@90 base + full pseudo override (no opacity sugar)
+//
+// scheme is EITHER a positional pair OR named prefixes, never both; a
+// trailing/leading slash pair member must be a full ref (dark-only is
+// spelled `dark:...`).
+import { isArray, isNumberish, isString } from '@ui0/util'
+
+import type { ColorPseudo, ColorScheme, ColorToken } from './color.types'
+
+export const ColorSchemeValues: ReadonlyArray<ColorScheme> = ['light', 'dark']
+export const ColorPseudoValues: ReadonlyArray<ColorPseudo> = ['hover', 'active', 'focus']
+
+const SPACE = /\s+/
+
+/** parse a `<ref>[@pct]` tail into ref + opacity (0..1) */
+export function parseRef(raw: string): { ref: string; opacity?: number } {
+  const at = raw.lastIndexOf('@')
+  if (at === -1) return { ref: raw }
+  const ref = raw.slice(0, at)
+  const pct = raw.slice(at + 1)
+  if (!ref || !isNumberish(pct)) throw new Error(`ui0 color: invalid ref "${raw}" (expected name[@pct])`)
+  const n = Number(pct)
+  if (n < 0 || n > 100) throw new Error(`ui0 color: opacity ${pct} out of 0..100 in "${raw}"`)
+  return { ref, opacity: n / 100 }
+}
+
+function parseToken(raw: string): ColorToken {
+  const segments = raw.split(':')
+  const out: ColorToken = { ref: '' }
+  while (segments.length > 1) {
+    const head = segments[0]
+    if ((ColorSchemeValues as ReadonlyArray<string>).includes(head)) {
+      out.scheme = head as ColorScheme
+    } else if ((ColorPseudoValues as ReadonlyArray<string>).includes(head)) {
+      out.pseudo = head as ColorPseudo
+    } else {
+      throw new Error(`ui0 color: unknown prefix "${head}" in "${raw}" (expected light|dark|hover|active|focus)`)
+    }
+    segments.shift()
+  }
+  Object.assign(out, parseRef(segments[0]))
+  if (!out.ref) throw new Error(`ui0 color: missing color ref in "${raw}"`)
+  return out
+}
+
+/** parse a color/fill prop value into tokens (one per layer) */
+export function parseColorProp(value: string | string[] | undefined | null): ColorToken[] {
+  const raws = (isString(value) ? value.split(SPACE) : isArray(value) ? value : [])
+    .map((x) => String(x).trim())
+    .filter(Boolean)
+
+  const tokens: ColorToken[] = []
+  let sawPair = false
+  let sawNamedScheme = false
+  for (const raw of raws) {
+    if (raw.includes('/')) {
+      const pair = raw.split('/')
+      if (pair.length !== 2 || !pair[0] || !pair[1])
+        throw new Error(`ui0 color: "${raw}" is not a light/dark pair (spell single-scheme as dark:ref)`)
+      if (pair[0].includes(':') || pair[1].includes(':'))
+        throw new Error(
+          `ui0 color: "${raw}" - pair segments must be plain refs (name[-ramp][@pct]); ` +
+            'prefixed parts need the named form: light:<ref> [pseudo:]<ref>'
+        )
+      tokens.push({ scheme: 'light', ...parseRef(pair[0]) })
+      tokens.push({ scheme: 'dark', ...parseRef(pair[1]) })
+      sawPair = true
+    } else {
+      const token = parseToken(raw)
+      if (token.scheme) sawNamedScheme = true
+      tokens.push(token)
+    }
+  }
+  if (sawPair && sawNamedScheme)
+    throw new Error('ui0 color: a positional `a/b` pair cannot mix with light:/dark: prefixes in one prop')
+  return tokens
+}

package/src/contracts/color/color.types.ts

@@ -0,0 +1,82 @@
+import type { ComponentColor, RgbTuple, Ui0ThemeColorRef } from '@ui0/types'
+
+/** the `color` prop: text/foreground paint. See color.token.ts for the dsl. */
+export interface ColorProps {
+  color?: Ui0ThemeColorRef
+}
+
+/** the `fill` prop: background paint. Same dsl as `color`. */
+export interface FillProps {
+  fill?: Ui0ThemeColorRef
+}
+
+/** the `gradient` prop: background-image linear-gradient composed from pool
+ * refs (`to-br error->success@80`). Resolved onto `--0-g-cur` as an
+ * inline style - see color.gradient.ts. */
+export interface GradientProps {
+  gradient?: Ui0ThemeColorRef
+}
+
+/** legacy alias kept for the package's public type exports */
+export interface Gradientable {
+  color?: ComponentColor
+}
+
+export type ThemeColorName = string
+export type ThemeColorPool = Record<ThemeColorName, ThemeColorEntry>
+
+/** the color contract's settings inside a theme preset (appearance config) -
+ * a flat pool: role/arbitrary name -> color entry (ramp expressions allowed) */
+export type ColorThemeAppearanceConfig = ThemeColorPool
+
+/** (l)ighten, (d)arken, (c)ontrast, (s)hade. */
+export type ThemeColorRampType = 'l' | 'd' | 'c' | 's'
+/** Color space the ramp math runs in - perceptual `oklch` or legacy `hsl`. */
+export type ThemeColorSpace = 'hsl' | 'oklch'
+
+export interface ColorOptions {
+  ramps?: ThemeColorRampType[]
+  space?: ThemeColorSpace
+}
+
+// `[ '#AAAAAA', '#FF11FF', 50 ]` - mix two colors (literals or `[r,g,b]`
+// triples) by `depth` percent.
+export type ThemeColorBlendExpr = [string | RgbTuple, string | RgbTuple, number]
+
+// "#hex" / "rgb(...)" / "{name}" / "{name}-{l|d|c|s}{step}"
+export type ThemeColorRef = string
+
+export type ThemeColorEntry =
+  | ThemeColorRef // bare alias, e.g. hlbg: 'sea-l4'
+  // `[ color, steps, options? ]` - base color (or a blend of two), ramp step
+  // count, and optional extra ramps / color space.
+  | [ThemeColorRef | ThemeColorBlendExpr, number, (ThemeColorRampType[] | ColorOptions)?]
+
+/** consumer-side color contract settings (ThemePluginConfig.contracts.color) */
+// the parsed prop-dsl token (see color.token.ts):
+//   [light:|dark:][hover:|active:|focus:]<ref>[already split into opacity]
+export type ColorScheme = 'light' | 'dark'
+export type ColorPseudo = 'hover' | 'active' | 'focus'
+
+export interface ColorToken {
+  scheme?: ColorScheme
+  pseudo?: ColorPseudo
+  /** pool reference: `name` or `name-{l|d|c|s}{step}` */
+  ref: string
+  /** 0..1; undefined = fully opaque */
+  opacity?: number
+}
+
+// registration: the contract announces itself to the package registries
+// (interface merging - no central import of the contracts anywhere)
+declare module '@ui0/types/theme' {
+  interface Ui0ThemePresetAppearanceConfig {
+    color?: ColorThemeAppearanceConfig
+  }
+  interface Ui0ThemeContractSettings {
+    /** `false` (or `true`) toggles the contract wholesale; an object is
+     * reserved for color contract options (none yet) */
+    color?: boolean | Record<string, unknown>
+  }
+  interface Ui0ThemeContracts extends ColorProps, FillProps, GradientProps {}
+}

package/src/contracts/color/index.md

@@ -0,0 +1,87 @@
+color/ - the paint contract: `color` (text), `fill` (background), `gradient`
+(background-image). v2 grammar (the v1 contract is archived at
+`../color-legacy/`, unregistered).
+
+THE PROP DSL (color.token.ts)
+
+prop := token (' ' token)* tokens = layers: base + overrides
+token := ref -> both schemes, no pseudo
+| ref '/' ref -> positional pair: light / dark
+| [scheme ':'][pseudo ':'] ref
+ref := name ['-' ramp] ['@' pct]
+
+scheme := light | dark pseudo := hover | active | focus
+
+success both schemes
+success@80/warning@100 light success@80, dark warning@100
+dark:warning dark only (light keeps the inherited/current)
+success hover:warning@90 base + full pseudo override (no opacity sugar)
+dark:hover:warning@90 pseudo override in one scheme
+
+Rules:
+
+- `@pct` is the only opacity spelling (no `-N`); `brand-2@50` is unambiguous
+  because the ramp suffix stays part of the ref.
+- Scheme is EITHER a positional pair OR named prefixes, never both in one
+  prop. Pair segments must be plain refs - a prefixed part
+  (`black@50/hover:warning`) throws, pointing to the named form
+  (`light:black@50 hover:warning`). Single-scheme is `dark:...`, never a
+  half-empty pair.
+- Prefix keywords are a closed set ({light, dark} x {hover, active, focus}),
+  parsed order-independently; anything else before `:` throws.
+
+THE PARSED TOKEN (color.types.ts)
+
+interface ColorToken {
+scheme?: 'light' | 'dark' // undefined = both
+pseudo?: 'hover' | 'active' | 'focus' // undefined = none
+ref: string // 'name' or 'name-{l|d|c|s}{step}', opaque
+opacity?: number // 0..1, undefined = opaque (normalized at parse)
+}
+
+parseColorProp(value: string | string[] | undefined | null): ColorToken[]
+
+DELIVERY (color.serialize.ts / color.contract.ts / color.scss)
+
+Selections ride classes, VALUES ride inline styles:
+
+- swatch setters ALWAYS classes: `[scheme-][pseudo-]{c|f}-<ref>` - selection
+  is conditional by nature (scheme/pseudo), and classes keep the theme layer
+  weak (apps override with their own css).
+- opacity VALUES always ride ELEMENT INLINE STYLES as context source vars:
+  `--0-{c|f}-src` (ungated), `-src-l|-d` (scheme), `-src-{hover|active|focus}`
+  (pseudo), `-src-{l|d}-{pseudo}` (combo). The generated theme css carries
+  NO opacity rules. The conditional pick lives in the component's color.use()
+  scss: per context a bridge rule (`:global(.theme_dark) &`, `&:hover`, ...)
+  re-declares the selected `--0-{c|f}-o` and the composed current reads it.
+  Fallback chains never cross schemes (a scheme-tagged source applies to
+  that scheme only; default 1). src vars reset to `initial` per element so
+  a translucent parent does not paint its children. `:global()` keeps the
+  theme's scheme classes unscoped - component module styles hash every bare
+  class literal.
+- gradient: `gradient="[to-<dir> ]ref[->ref...]"` (to-right|to-left|to-top|
+  to-bottom|to-tr|to-tl|to-br|to-bl, default to-bottom) compiles to
+  `--0-g-cur` as an inline style of LIVE var() references - gradients are
+  compositions, not selections, so they get scheme-adaptivity through token
+  indirection with zero gradient-specific classes. Consumed by the
+  `background-image` part of the color.apply() mixin.
+
+GENERATOR (color.generator.ts)
+
+Emits per pool name: swatch setters x 2 slots x {ungated, .theme_light,
+.theme_dark} x {none, hover, active, focus} - nothing else. Names hash with
+the same name-only sha256 the css-modules distiller uses (src/generator/hash.ts),
+so the runtime resolves any class without a registry. The used-tokens
+resolver is planned to prune the grid.
+
+FILES
+
+color.types.ts props + ColorToken + pool config types (shared with generator/pool.ts)
+color.token.ts the prop-dsl parser (parseColorProp / parseRef)
+color.serialize.ts tokens -> {classes, styles}
+color.gradient.ts the gradient prop -> `--0-g-cur` value
+color.contract.ts the deal: one parse pass per prop change, shared by classes()/styles()
+color.generator.ts the build-time endpoint (vars + setter classes)
+color.scss use/apply mixins (composed slots incl. --0-g-cur)
+color.module.css markers: colored, filled, gradiented
+color.keys.ts provide/inject keys for the `inherit` passthrough

package/src/contracts/color/index.ts

@@ -0,0 +1,25 @@
+import type { ThemeContract } from '@ui0/types'
+
+import { ThemeContractFlags } from '../../constants'
+import { colorDeal } from './color.contract'
+import { ColorContractKey, ColorRefKey } from './color.keys'
+import type { ColorProps, GradientProps, FillProps } from './color.types'
+
+export { default as $style } from './color.module.css'
+export type * from './color.types'
+export * from './color.keys'
+
+export const ColorPropsKeys: ReadonlyArray<keyof (GradientProps & ColorProps & FillProps)> = [
+  'color',
+  'fill',
+  'gradient'
+]
+
+export const color: ThemeContract = {
+  name: 'color',
+  key: ColorContractKey,
+  flag: ThemeContractFlags.dealer + ThemeContractFlags.generator,
+  ref: ColorRefKey,
+  deal: colorDeal,
+  props: ColorPropsKeys
+}

package/src/contracts/contract.ts

@@ -0,0 +1,115 @@
+import type { AnyProps, ClassList, CSSModuleClassList, Indexed, StyleList } from '@ui0/types'
+import type { ContractProvider, ContractRefs, ThemeContract, ThemeContractName, Ui0ThemeContracts } from '@ui0/types'
+import { isArray, isString } from '@ui0/util'
+function createProviderInstance(name: string, props?: Ui0ThemeContracts, styles?: CSSModuleClassList) {
+  const provider = {}
+}
+export class ThemeContractInstance implements ContractProvider {
+  props: AnyProps
+  /**
+   * context have any provided props from styler's
+   */
+  context: ContractRefs | null
+  $styles: CSSModuleClassList
+  name: string
+  classList: ClassList = []
+  styleList: StyleList = {}
+  contracts: Partial<Record<ThemeContractName, ThemeContract>>
+
+  constructor(name: string, props?: Ui0ThemeContracts, styles?: CSSModuleClassList) {
+    this.$styles = styles ?? {}
+    this.props = props ?? {}
+    this.name = name
+    this.context = null
+    this.contracts = {}
+  }
+
+  public add(contract: ThemeContract) {
+    this.contracts[contract.name] = contract
+  }
+  public prop(name: keyof Ui0ThemeContracts | Array<keyof Ui0ThemeContracts>) {
+    const jobs: Indexed<ThemeContract> = {}
+    const instance = this
+
+    for (const contract of Object.values(this.contracts)) {
+      if (isArray(name)) {
+        name.forEach((n) => {
+          if (contract.props?.includes(n)) {
+            jobs[contract.name] = contract.deal
+          }
+        })
+      } else if (isString(name)) {
+        if (contract.props?.includes(name)) {
+          jobs[contract.name] = contract
+        }
+      }
+      contract?.props?.includes(name)
+    }
+    return {
+      styles() {
+        let out: StyleList = {}
+        for (const contract of Object.values(jobs)) {
+          const deal = contract?.deal?.(instance)
+          if (deal) out = { ...out, ...deal.styles() }
+          //   if (deal && CONTRACT_PROPS[contract].some((p) => props[p])) {
+          //     out = { ...out, ...deal.styles(props) }
+          //   }
+        }
+        return out
+      },
+      classes() {
+        const out: ClassList = []
+        for (const contract of Object.values(jobs)) {
+          const deal = contract?.deal?.(instance)
+          if (deal) out.push(...deal.classes())
+        }
+        return out
+      }
+    }
+  }
+
+  public remove(name: ThemeContractName) {
+    delete this.contracts[name]
+  }
+
+  public setContext(p: ContractRefs) {
+    this.context = p
+  }
+
+  public classes(props_?: AnyProps, $styles = this.$styles) {
+    const props = props_ ?? this.props
+    const out: ClassList = []
+    for (const contract of Object.values(this.contracts)) {
+      const deal = contract?.deal?.(this)
+      if (deal) out.push(...deal.classes(props as Ui0ThemeContracts, $styles))
+    }
+    return out
+  }
+
+  public styles(props_?: AnyProps) {
+    const props = props_ ?? this.props
+    let out: StyleList = {}
+    for (const contract of Object.keys(this.contracts) as ThemeContractName[]) {
+      const deal = this.contracts[contract]?.deal?.(this)
+      if (deal) out = { ...out, ...deal.styles(props) }
+      //   if (deal && CONTRACT_PROPS[contract].some((p) => props[p])) {
+      //     out = { ...out, ...deal.styles(props) }
+      //   }
+    }
+    return out
+  }
+
+  /**
+   * Virtual's classes and styles injector
+   * @param data
+   * @private
+   */
+  public inject(data?: any) {
+    if (isArray(data)) {
+      // dirty hack to compute it faster
+      // in reality we need to check-mark every item of array1 in array2
+      if (data.indexOf(this.classList[0]) === -1) return [...this.classList, ...data]
+      else return data
+    } else return { ...this.styleList, ...data }
+  }
+}

package/src/contracts/disabled/disabled.contract.ts

@@ -0,0 +1,32 @@
+// The disabled contract's processing endpoint: the `disabled` prop maps to
+// the hashed `.disabled` setter class; `inherit` reads the provided ref.
+import type { ClassList, CSSModuleClassList } from '@ui0/types'
+import type { ContractProvider, ThemeContractDeal } from '@ui0/types'
+import { mergeCssModulesStyles } from '@ui0/util'
+
+import { EMPTY_OBJ } from '../../constants'
+import type { DisabledProps } from './disabled.types'
+
+import $disabled from './disabled.module.css'
+
+function disabledClasses(p: DisabledProps, s?: CSSModuleClassList): ClassList {
+  const $ = mergeCssModulesStyles($disabled, s)
+  if (p.disabled) return [$.disabled]
+  return []
+}
+
+export function disabledDeal(instance: ContractProvider): ThemeContractDeal {
+  const props = instance.props
+
+  return {
+    classes: () => {
+      if (instance.context) {
+        if (props.disabled === 'inherit' && instance.context.disabled) {
+          return instance.inject(disabledClasses({ disabled: instance.context.disabled.value }, instance.$styles))
+        }
+      }
+      return instance.inject(disabledClasses(props, instance.$styles))
+    },
+    styles: () => instance.inject(EMPTY_OBJ)
+  }
+}

package/src/contracts/disabled/disabled.generator.ts

@@ -0,0 +1,32 @@
+// The disabled contract's generator endpoint: the .disabled setter applies
+// the disabled-state look (shipped as static css in disabled.inject.module.css,
+// selectors hashed at build); the opacity value is theme-authored
+// (Ui0ThemePresetAppearanceConfig.disabled.opacity) and lands on the theme block.
+import type { CSSModuleClassList, VarList } from '@ui0/types'
+import type { ThemeContractGenerator } from '@ui0/types'
+
+import type { ContractFactory } from '../generator'
+import type { DisabledThemeAppearanceConfig } from './disabled.types'
+
+import disabledCss from './disabled.inject.module.css'
+import $disabled from './disabled.module.css'
+
+const disabledGenerator: ContractFactory = (ctx): ThemeContractGenerator => {
+  const { config } = ctx
+
+  function vars(): Record<string, VarList> {
+    const disabled = (config as { disabled?: DisabledThemeAppearanceConfig }).disabled
+    if (disabled?.opacity === undefined) return {}
+    return { dis: { o: disabled.opacity } }
+  }
+
+  return {
+    namespace: 'dis',
+    vars: (scheme) => (scheme ? {} : vars()),
+    css: () => disabledCss,
+    class: (): CSSModuleClassList => ({ ...$disabled }),
+    styles: () => ({})
+  }
+}
+
+export default disabledGenerator

package/src/contracts/disabled/disabled.inject.module.css

@@ -0,0 +1,5 @@
+@value disabled from './disabled.module.css';
+
+.disabled {
+  opacity: var(--0-dis-o, 0.5);
+}

package/src/contracts/disabled/disabled.keys.ts

@@ -0,0 +1,6 @@
+import type { ThemeContractDeal } from '@ui0/types'
+import type { InjectionKey, Ref } from 'vue'
+
+export const DisabledRefKey = Symbol('DisabledRefKey') as InjectionKey<Ref<boolean>>
+
+export const DisabledContractKey = Symbol('DisabledContractKey') as InjectionKey<ThemeContractDeal>

package/src/contracts/disabled/disabled.module.css

@@ -0,0 +1,3 @@
+.disabled {
+  /*@*/
+}

package/src/contracts/disabled/disabled.scss

@@ -0,0 +1,3 @@
+@mixin filter {
+  filter: grayscale(80%) opacity(70%);
+}

package/src/contracts/disabled/disabled.types.ts

@@ -0,0 +1,19 @@
+export interface DisabledProps {
+  disabled?: boolean
+}
+
+export interface DisabledThemeAppearanceConfig {
+  opacity?: number
+}
+
+// registration: the contract announces itself to the package registries
+// (interface merging - no central import of the contracts anywhere)
+declare module '@ui0/types/theme' {
+  interface Ui0ThemePresetAppearanceConfig {
+    disabled?: DisabledThemeAppearanceConfig
+  }
+  interface Ui0ThemeContractSettings {
+    disabled?: boolean
+  }
+  interface Ui0ThemeContracts extends DisabledProps {}
+}