postcss-custom-functions

.github/ISSUE_TEMPLATE/css-issue.yml

@@ -82,6 +82,7 @@ body:
         - PostCSS Container Rule Prelude List
         - PostCSS Content Alt Text
         - PostCSS Contrast Color Functions
+        - PostCSS Custom Functions
         - PostCSS Custom Media Queries
         - PostCSS Custom Properties
         - PostCSS Custom Selectors

.github/ISSUE_TEMPLATE/plugin-issue.yml

@@ -79,6 +79,7 @@ body:
         - PostCSS Container Rule Prelude List
         - PostCSS Content Alt Text
         - PostCSS Contrast Color Functions
+        - PostCSS Custom Functions
         - PostCSS Custom Media Queries
         - PostCSS Custom Properties
         - PostCSS Custom Selectors

.github/labeler.yml

@@ -161,6 +161,12 @@
       - plugins/postcss-contrast-color-function/**
       - experimental/postcss-contrast-color-function/**
 
+"plugins/postcss-custom-functions":
+  - changed-files:
+    - any-glob-to-any-file:
+      - plugins/postcss-custom-functions/**
+      - experimental/postcss-custom-functions/**
+
 "plugins/postcss-custom-media":
   - changed-files:
     - any-glob-to-any-file:

packages/custom-function-parser/.gitignore

@@ -0,0 +1,6 @@
+node_modules
+package-lock.json
+yarn.lock
+*.result.css
+*.result.css.map
+*.result.json

packages/custom-function-parser/.nvmrc

@@ -0,0 +1 @@
+v26.1.0

packages/custom-function-parser/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changes to Custom Function Parser
+
+### Unreleased (major)
+
+- Initial version

packages/custom-function-parser/LICENSE.md

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright 2022 Romain Menke, Antonio Laguna <antonio@laguna.es>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

packages/custom-function-parser/README.md

@@ -0,0 +1,28 @@
+# Custom Function Parser <img src="https://cssdb.org/images/css.svg" alt="for CSS" width="90" height="90" align="right">
+
+[<img alt="npm version" src="https://img.shields.io/npm/v/@csstools/custom-function-parser.svg" height="20">][npm-url]
+[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/actions/workflows/test.yml/badge.svg?branch=main" height="20">][cli-url]
+[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]
+
+Implemented from : https://www.w3.org/TR/mediaqueries-5/
+
+## Usage
+
+Add [Custom Function Parser] to your project:
+
+```bash
+npm install @csstools/custom-function-parser @csstools/css-parser-algorithms @csstools/css-tokenizer --save-dev
+```
+
+[Custom Function Parser] depends on our CSS tokenizer and parser algorithms.
+It must be used together with `@csstools/css-tokenizer` and `@csstools/css-parser-algorithms`.
+
+```ts
+// TODO
+```
+
+[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
+[discord]: https://discord.gg/bUadyRwkJS
+[npm-url]: https://www.npmjs.com/package/@csstools/custom-function-parser
+
+[Custom Function Parser]: https://github.com/csstools/postcss-plugins/tree/main/packages/custom-function-parser

packages/custom-function-parser/api-extractor.json

@@ -0,0 +1,7 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "../../api-extractor.json",
+	"docModel": {
+		"enabled": true
+	}
+}

packages/custom-function-parser/dist/index.d.ts

@@ -0,0 +1,72 @@
+import type { CSSToken } from '@csstools/css-tokenizer';
+import { FunctionNode } from '@csstools/css-parser-algorithms';
+import type { ParseError } from '@csstools/css-tokenizer';
+import type { TokenColon } from '@csstools/css-tokenizer';
+import type { TokenIdent } from '@csstools/css-tokenizer';
+
+export declare class CustomFunction {
+    type: NodeType;
+    function: FunctionNode;
+    parameters: Array<FunctionParameter>;
+    returnsKeyword: Array<CSSToken>;
+    returnType: Array<CSSToken>;
+    before: Array<CSSToken>;
+    after: Array<CSSToken>;
+    constructor(fn: FunctionNode, parameters: Array<FunctionParameter>, returnsKeyword: Array<CSSToken>, returnType: Array<CSSToken>, before?: Array<CSSToken>, after?: Array<CSSToken>);
+    getName(): string;
+    getReturnType(): string;
+    tokens(): Array<CSSToken>;
+    toString(): string;
+    /**
+     * @internal
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * @internal
+     */
+    isCustomFunction(): this is CustomFunction;
+    static isCustomFunction(x: unknown): x is CustomFunction;
+}
+
+export declare class FunctionParameter {
+    type: NodeType;
+    name: TokenIdent;
+    argumentType: Array<CSSToken>;
+    colon: TokenColon | null;
+    defaultValue: Array<CSSToken>;
+    before: Array<CSSToken>;
+    after: Array<CSSToken>;
+    constructor(name: TokenIdent, argumentType: Array<CSSToken>, colon: TokenColon | null, defaultValue: Array<CSSToken>, before?: Array<CSSToken>, after?: Array<CSSToken>);
+    getName(): string;
+    getNameToken(): TokenIdent | null;
+    getArgumentType(): string;
+    getDefaultValue(): string;
+    /**
+     * @internal
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * @internal
+     */
+    isFunctionParameter(): this is FunctionParameter;
+    static isFunctionParameter(x: unknown): x is FunctionParameter;
+}
+
+export declare function isCustomFunction(x: unknown): x is CustomFunction;
+
+export declare function isFunctionParameter(x: unknown): x is FunctionParameter;
+
+export declare enum NodeType {
+    CustomFunction = "custom-function",
+    FunctionParameter = "function-parameter"
+}
+
+export declare function parse(source: string, options?: {
+    onParseError?: (error: ParseError) => void;
+}): CustomFunction | false;
+
+export declare function parseFromTokens(tokens: Array<CSSToken>, options?: {
+    onParseError?: (error: ParseError) => void;
+}): CustomFunction | false;
+
+export { }

packages/custom-function-parser/dist/index.mjs

@@ -0,0 +1 @@
+import{parseListOfComponentValues as t,isWhiteSpaceOrCommentNode as e,isFunctionNode as r,isTokenNode as n,isWhitespaceNode as s,isSimpleBlockNode as o}from"@csstools/css-parser-algorithms";import{stringify as a,isTokenComment as i,isTokenIdent as u,isTokenComma as l,isTokenDelim as c,isTokenColon as f,isTokenOpenCurly as m,tokenize as h}from"@csstools/css-tokenizer";var p;!function(t){t.CustomFunction="custom-function",t.FunctionParameter="function-parameter"}(p||(p={}));class CustomFunction{type=p.CustomFunction;function;parameters;returnsKeyword;returnType;before;after;constructor(t,e,r,n,s=[],o=[]){this.function=t,this.parameters=e,this.returnsKeyword=r,this.returnType=n,this.before=s,this.after=o}getName(){return this.function.getName()}getReturnType(){const n=t(this.returnType).filter(t=>!e(t));return 1===n.length&&r(n[0])&&"type"===n[0].getName().toLowerCase()?a(...n[0].value.flatMap(t=>t.tokens()).filter(t=>!i(t))).trim():a(...this.returnType.filter(t=>!i(t))).trim()}tokens(){return[...this.before,...this.function.tokens(),...this.returnsKeyword,...this.returnType,...this.after]}toString(){return a(...this.before)+a(...this.function.tokens())+a(...this.returnsKeyword)+a(...this.returnType)+a(...this.after)}toJSON(){return{type:this.type,name:this.getName(),string:this.toString(),tokens:this.tokens(),parameters:this.parameters.map(t=>t.toJSON()),returnsKeyword:this.returnsKeyword,returnType:this.returnType,before:this.before,after:this.after}}isCustomFunction(){return CustomFunction.isCustomFunction(this)}static isCustomFunction(t){return!!t&&(t instanceof CustomFunction&&t.type===p.CustomFunction)}}class FunctionParameter{type=p.FunctionParameter;name;argumentType;colon;defaultValue;before;after;constructor(t,e,r,n,s=[],o=[]){this.name=t,this.argumentType=e,this.colon=r,this.defaultValue=n,this.before=s,this.after=o}getName(){return this.name[4].value}getNameToken(){return this.name}getArgumentType(){return a(...this.argumentType.filter(t=>!i(t))).trim()}getDefaultValue(){return a(...this.defaultValue).trim()}toJSON(){return{type:this.type,name:this.getName(),argumentType:this.argumentType,colon:this.colon,defaultValue:this.defaultValue,before:this.before,after:this.after}}isFunctionParameter(){return FunctionParameter.isFunctionParameter(this)}static isFunctionParameter(t){return!!t&&(t instanceof FunctionParameter&&t.type===p.FunctionParameter)}}function parseCustomFunction(t){let s=null,o=-1,a=-1,i=-1,l=t.length;for(let l=0;l<t.length;l++){const c=t[l];if(!e(c)){if(-1!==o||!r(c)){if(-1!==o&&-1===a&&n(c)){const t=c.value;if(!u(t))return!1;if("returns"!==t[4].value.toLowerCase())return!1;a=l;continue}if(-1!==a){i=l;break}return!1}if(!c.getName().startsWith("--"))return!1;o=l,s=c}}if(-1!==a&&-1===i)return!1;if(!s)return!1;for(let r=t.length-1;r>i;r--){const n=t[r];if(!e(n))break;l=r}const c=parseFunctionParameters(s.value);return!!c&&new CustomFunction(s,c,-1===i?[]:t.slice(o+1,i).flatMap(t=>t.tokens()),-1===i?[]:t.slice(i,l).flatMap(t=>t.tokens()),t.slice(0,o).flatMap(t=>t.tokens()),t.slice(l).flatMap(t=>t.tokens()))}function parseFunctionParameters(t){if(!t.some(t=>!e(t)))return[];const r=[],n=new Set;for(let e=0;e<t.length;e++){const s=parseFunctionParameter(t.slice(e));if(!s)return!1;const o=s.node.getName();if(n.has(o))return!1;n.add(o),e+=s.advance,r.push(s.node)}return r}function parseFunctionParameter(t){let a=0,i=-1,h=null,p=-1,F=null,g=-1,v=t.length,y=0;for(;y<t.length;y++){const r=t[y];if(!e(r)){if(0===a&&n(r)&&l(r.value)){v=y;break}if(-1===i){if(n(r)&&u(r.value)&&r.value[4].value.startsWith("--")){i=y,h=r.value;continue}return!1}if(-1===p&&n(r)&&c(r.value)&&"<"===r.value[4].value)a++;else if(-1===p&&a>0&&n(r)&&c(r.value)&&">"===r.value[4].value)a--;else if(-1===p&&0===a&&n(r)&&f(r.value))p=y,F=r.value;else if(-1===p){if(-1!==p)return!1}else g=y}}if(!h)return!1;if(-1!==p&&-1===g)return!1;const k=-1!==p?p-1:y-1;for(let e=t.length-1;e>Math.max(k,g);e--){const r=t[e];if(!s(r))break;v=e}let P;{const n=t.slice(i+1,k+1),s=n.filter(t=>!e(t));P=1===s.length&&r(s[0])&&"type"===s[0].getName().toLowerCase()?s[0].value.flatMap(t=>t.tokens()):n.flatMap(t=>t.tokens())}let T=[];if(-1!==g){const r=t.slice(p+1,v);if(hasTopLevelImportant(r))return!1;const n=r.filter(t=>!e(t));T=1===n.length&&o(n[0])&&m(n[0].startToken)?n[0].value.flatMap(t=>t.tokens()):r.flatMap(t=>t.tokens())}return{advance:y,node:new FunctionParameter(h,P,F,T,t.slice(0,i).flatMap(t=>t.tokens()),t.slice(v,y+1).flatMap(t=>t.tokens()))}}function hasTopLevelImportant(t){for(let r=0;r<t.length;r++){const s=t[r];if(n(s)&&c(s.value)&&"!"===s.value[4].value)for(let s=r+1;s<t.length;s++){const r=t[s];if(!e(r)){if(n(r)&&u(r.value)&&"important"===r.value[4].value.toLowerCase())return!0;break}}}return!1}function parseFromTokens(e,r){let n=!1;const s=t(e,{onParseError:t=>{n=!0,r?.onParseError?.(t)}});return!n&&parseCustomFunction(s)}function parse(t,e){return parseFromTokens(h({css:t},{onParseError:e?.onParseError}),e)}function isCustomFunction(t){return CustomFunction.isCustomFunction(t)}function isFunctionParameter(t){return FunctionParameter.isFunctionParameter(t)}export{CustomFunction,FunctionParameter,p as NodeType,isCustomFunction,isFunctionParameter,parse,parseFromTokens};