Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions packages/utilities-for-private-properties/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,5 @@
### Unreleased (major)

- Initial version
- Add an explicit scope for substituted nodes
- Add a `preserve` option that keeps `@private` rules
11 changes: 11 additions & 0 deletions packages/utilities-for-private-properties/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,17 @@ const registrations = transpiler.transpile(root.nodes);
root.append(...registrations);
```

Nodes that are substituted into a style rule but are not its children, for example the contents of
an `@contents` block, can be transpiled in the scope of that style rule:

```ts
transpiler.transpile(nodes, { scope: styleRule });
```

With `preserve: true` the `@private` rules are kept and references inside `@apply` and `@contents`
blocks are left alone. Transpiled declarations are still hoisted, so the original notation keeps
working where `@private` is supported.

`@property` rules are only hoisted out of `@layer`, `@media` and `@supports` group rules. Registrations inside `@container`, `@scope` or `@starting-style` are left untouched, because those conditions cannot be preserved at the top level.

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
Expand Down
22 changes: 21 additions & 1 deletion packages/utilities-for-private-properties/dist/index.d.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import type { AtRule } from 'postcss';
import type { ChildNode } from 'postcss';
import type { Rule } from 'postcss';

/**
* Create a transpiler for private custom properties.
Expand All @@ -10,14 +11,25 @@ import type { ChildNode } from 'postcss';
*/
export declare function createPrivatePropertyTranspiler(options?: PrivatePropertyTranspilerOptions): PrivatePropertyTranspiler;

export declare type PrivatePropertyTranspileOptions = {
/**
* Style rule that owns the private property names of `nodes`.
*
* Use this when `nodes` are substituted into a style rule but are not its
* direct children, for example a `@contents` block that is authored at an
* `@apply` site and placed inside a mixin body.
*/
scope?: Rule;
};

export declare type PrivatePropertyTranspiler = {
/**
* Transpile private rules and private property references in `nodes`.
*
* Mutates `nodes` in place and returns the `@property` rules that must be
* appended to the root of the tree.
*/
transpile: (nodes: Array<ChildNode>) => Array<AtRule>;
transpile: (nodes: Array<ChildNode>, options?: PrivatePropertyTranspileOptions) => Array<AtRule>;
};

export declare type PrivatePropertyTranspilerOptions = {
Expand All @@ -33,6 +45,14 @@ export declare type PrivatePropertyTranspilerOptions = {
* private properties.
*/
allowUntranspiledMixins?: boolean;
/**
* Keep `@private` rules and leave references inside `@apply` and `@contents`
* blocks alone.
*
* Transpiled declarations are still hoisted, so the original notation keeps
* working where `@private` is supported.
*/
preserve?: boolean;
};

export { }
2 changes: 1 addition & 1 deletion packages/utilities-for-private-properties/dist/index.mjs

Large diffs are not rendered by default.

Original file line number Diff line number Diff line change
Expand Up @@ -234,6 +234,41 @@
],
"name": "createPrivatePropertyTranspiler"
},
{
"kind": "TypeAlias",
"canonicalReference": "@csstools/utilities-for-private-properties!PrivatePropertyTranspileOptions:type",
"docComment": "",
"excerptTokens": [
{
"kind": "Content",
"text": "export type PrivatePropertyTranspileOptions = "
},
{
"kind": "Content",
"text": "{\n scope?: "
},
{
"kind": "Reference",
"text": "Rule",
"canonicalReference": "postcss!Rule_:class"
},
{
"kind": "Content",
"text": ";\n}"
},
{
"kind": "Content",
"text": ";"
}
],
"fileUrlPath": "dist/_types/transpiler.d.ts",
"releaseTag": "Public",
"name": "PrivatePropertyTranspileOptions",
"typeTokenRange": {
"startIndex": 1,
"endIndex": 4
}
},
{
"kind": "TypeAlias",
"canonicalReference": "@csstools/utilities-for-private-properties!PrivatePropertyTranspiler:type",
Expand Down Expand Up @@ -263,7 +298,16 @@
},
{
"kind": "Content",
"text": ">) => "
"text": ">, options?: "
},
{
"kind": "Reference",
"text": "PrivatePropertyTranspileOptions",
"canonicalReference": "@csstools/utilities-for-private-properties!PrivatePropertyTranspileOptions:type"
},
{
"kind": "Content",
"text": ") => "
},
{
"kind": "Reference",
Expand Down Expand Up @@ -293,7 +337,7 @@
"name": "PrivatePropertyTranspiler",
"typeTokenRange": {
"startIndex": 1,
"endIndex": 10
"endIndex": 12
}
},
{
Expand All @@ -307,7 +351,7 @@
},
{
"kind": "Content",
"text": "{\n namespace?: string;\n allowUntranspiledMixins?: boolean;\n}"
"text": "{\n namespace?: string;\n allowUntranspiledMixins?: boolean;\n preserve?: boolean;\n}"
},
{
"kind": "Content",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,15 @@ Description
</th></tr></thead>
<tbody><tr><td>

[PrivatePropertyTranspileOptions](./utilities-for-private-properties.privatepropertytranspileoptions.md)


</td><td>


</td></tr>
<tr><td>

[PrivatePropertyTranspiler](./utilities-for-private-properties.privatepropertytranspiler.md)


Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](./index.md) &gt; [@csstools/utilities-for-private-properties](./utilities-for-private-properties.md) &gt; [PrivatePropertyTranspileOptions](./utilities-for-private-properties.privatepropertytranspileoptions.md)

## PrivatePropertyTranspileOptions type

**Signature:**

```typescript
export type PrivatePropertyTranspileOptions = {
scope?: Rule;
};
```
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@

```typescript
export type PrivatePropertyTranspiler = {
transpile: (nodes: Array<ChildNode>) => Array<AtRule>;
transpile: (nodes: Array<ChildNode>, options?: PrivatePropertyTranspileOptions) => Array<AtRule>;
};
```
**References:** [PrivatePropertyTranspileOptions](./utilities-for-private-properties.privatepropertytranspileoptions.md)

Original file line number Diff line number Diff line change
Expand Up @@ -10,5 +10,6 @@
export type PrivatePropertyTranspilerOptions = {
namespace?: string;
allowUntranspiledMixins?: boolean;
preserve?: boolean;
};
```
10 changes: 5 additions & 5 deletions packages/utilities-for-private-properties/src/index.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
import type { AtRule, ChildNode } from 'postcss';
import type { PrivatePropertyTranspilerOptions } from './transpiler';
import type { PrivatePropertyTranspileOptions, PrivatePropertyTranspilerOptions } from './transpiler';
import { Transpiler } from './transpiler';

export type { PrivatePropertyTranspilerOptions } from './transpiler';
export type { PrivatePropertyTranspileOptions, PrivatePropertyTranspilerOptions } from './transpiler';

export type PrivatePropertyTranspiler = {
/**
Expand All @@ -11,7 +11,7 @@ export type PrivatePropertyTranspiler = {
* Mutates `nodes` in place and returns the `@property` rules that must be
* appended to the root of the tree.
*/
transpile: (nodes: Array<ChildNode>) => Array<AtRule>,
transpile: (nodes: Array<ChildNode>, options?: PrivatePropertyTranspileOptions) => Array<AtRule>,
};

/**
Expand All @@ -25,8 +25,8 @@ export function createPrivatePropertyTranspiler(options?: PrivatePropertyTranspi
const transpiler = new Transpiler(options);

return {
transpile(nodes: Array<ChildNode>): Array<AtRule> {
return transpiler.transpile(nodes);
transpile(nodes: Array<ChildNode>, transpileOptions?: PrivatePropertyTranspileOptions): Array<AtRule> {
return transpiler.transpile(nodes, transpileOptions);
},
};
}
Loading
Loading