Contract with ICSS

[TrySound]

This thread to summarize all contracts between icss plugins

• postcss-icss-selectors
• postcss-icss-values
• postcss-icss-composes

This plugins do not require contracts

• postcss-icss-import
• postcss-icss-url
• postcss-icss-keyframes

Values plugin before selectors and composes plugins

If local identifier already exists :import keys then skip scoping

@value local1 from 'path';
.local1 {}
.local2 { composes: local1; }
.local3 { composes: exported from 'path'; }

/* after values */

:import('path') {
  __local1: local1
}
:export {
  local1: __local1
}
.__local1 {}
.local2 { composes: __local1; }
.local3 { composes: exported from 'path'; }

/* after selectors and compose */

:import('path') {
  __local1: local1;
  __exported: exported;
}
:export {
  local1: __local1;
  local2: __scope__local2;
  local3: __scope__local3;
}
.__local1 {}
.__scope__local2 {}
.__scope__local3 {}

Values plugin after selectors and composes plugin

Values can't be detected in compound exported values

@value local2 from 'path';
.local1 {}
.local2 { composes: local1; }
.local3 { composes: exported from 'path'; }

/* after selectors and compose */

:import('path') {
  __exported: exported;
}
:export {
  local1: __scope__local1;
  local2: __scope__local2 __scope__local1;
  local3: __scope__local3 __exported;
}
@value local2 from 'path';
.__scope__local1 {}
.__scope__local2 {}
.__scope__local3 {}

Composes plugin before selectors plugin

If exported key already exists then apply scoping and replace exported value if present in scoped list
Else add identifier as key and scoped class name as value

.local1 {}
.local2 { composes: local1; }
.local3 { composes: exported from 'path'; }

/* after composes */

:import('path') {
  __exported: exported
}
:export {
  local2: local1;
  local3: __exported;
}
.local1 {}
.local2 {}

/* after selectors */

:import('path') {
  __exported: exported
}
:export {
  local1: __scope__local1;
  local2: __scope__local2 __scope__local1;
  local3: __scope__local3 __exported;
}
.__scope__local1 {}
.__scope__local2 {}
.__scope__local3 {}

Composes plugin after selectors plugin

If exported value contains class name then append composed one
else add class name as key and composed one as value

.local1 {}
.local2 {
  composes: local1;
}
.local3 {
  composes: exported from 'path';
}

/* after selectors */

:export {
  local1: __scope__local1;
  local2: __scope__local2;
  local3: __scope__local3
}
.__scope__local1 {}
.__scope__local2 {
  composes: local1;
}
.__scope__local3 {
  composes: exported from 'path';
}

/* after composes */

:import('path') {
  __exported: exported
}
:export {
  local1: __scope__local1;
  local2: __scope__local2 __scope__local1;
  local3: __scope__local3 __exported
}
.__scope__local1 {}
.__scope__local2 {}
.__scope__local3 {}

[TrySound]

@michael-ciniawsky @evilebottnawi
As you can see if we allow to use values with selectors order becomes important.
As work around we can introduce :external pseudo-class which will be skipped by scope plugin.
What do you think?

[alexander-akait]

@TrySound good question, i wonder how other plugins do this, example cssnext, also we can migrate to mono repo and avoid this situation (as do cssnano).

[TrySound]

As a workaround we may consider first word in exported value as alias.

[TrySound]

Yeah. It will be semantic contract caz composes classes should be always appended.

[TrySound]

Or we can use separate contract between these plugins via messages. This will let to provide more info.

[TrySound]

Messages contract

postcss-icss-selectors and postcss-icss-keyframes

pass each defined identifier

{
  type: 'modules-scoped',
  name: string,
  value: string
}

postcss-icss-values matches scoped values by local keys
postcss-icss-composes matches local keys by scoped values

postcss-icss-values

passes message for each imported value (TODO: should we pass for all values?)

{
  type: 'modules-value',
  name: string,
  value: string
}

postcss-icss-selectors skips selector if values has equal value
postcss-icss-compose not warns on not existent local identifier and appends value

postcss-icss-composes

passes each composition pair

{
  type: 'modules-composed',
  name: string,
  value: string
}

postcss-icss-selectors prepends scoped identifier to matched by name local one

This contracts let's plugins rely on each other but still be optional and independent.

[TrySound]

I decide to rely on ICSS contract scheme. Values plugin will use messages to resolve original class names.