{"id":16124391,"url":"https://github.com/jongacnik/gr8-util","last_synced_at":"2025-03-18T12:31:39.723Z","repository":{"id":68335721,"uuid":"97135469","full_name":"jongacnik/gr8-util","owner":"jongacnik","description":"A little function for generating functional css utilities","archived":false,"fork":false,"pushed_at":"2018-02-02T08:09:23.000Z","size":43,"stargazers_count":6,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-28T09:21:06.423Z","etag":null,"topics":["css","functional","utilities"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jongacnik.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-07-13T15:01:41.000Z","updated_at":"2023-03-27T01:29:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"2d83b597-2220-4622-8bba-e31893594db5","html_url":"https://github.com/jongacnik/gr8-util","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jongacnik%2Fgr8-util","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jongacnik%2Fgr8-util/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jongacnik%2Fgr8-util/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jongacnik%2Fgr8-util/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jongacnik","download_url":"https://codeload.github.com/jongacnik/gr8-util/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243926065,"owners_count":20369911,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["css","functional","utilities"],"created_at":"2024-10-09T21:21:12.547Z","updated_at":"2025-03-18T12:31:39.716Z","avatar_url":"https://github.com/jongacnik.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003egr8-util\u003c/h1\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/gr8-util\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/gr8-util.svg?style=flat-square\" alt=\"NPM version\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/feross/standard\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square\" alt=\"NPM version\" /\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\nA little function for generating functional css utilities.\n\n## Usage\n\nGiven some options, `gr8-util` returns a string of css utilities. It does its best to generate concise and logical css selectors.\n\n```js\nvar util = require('gr8-util')\n\nvar css = util({\n  prop: 'display',\n  vals: [\n    'block',\n    'inline-block',\n    'inline',\n    'table',\n    'table-cell',\n    'table-row',\n    'flex',\n    'none'\n  ]\n})\n\nconsole.log(css)\n```\n\n```css\n.db{display:block}\n.dib{display:inline-block}\n.di{display:inline}\n.dt{display:table}\n.dtc{display:table-cell}\n.dtr{display:table-row}\n.df{display:flex}\n.dn{display:none}\n```\n\n## API\n\n### `css = util([opts])`\n\nGenerate a string of css utility rules. `opts` accepts the following values:\n\n- `opts.prop` **[String | Array | Object]** css property(ies) ***required**\n- `opts.vals` **[Number | String | Array | Object]** css values ***required**\n- `opts.modifiers` **[String | Array | Object]** selector modifier(s)\n- `opts.unit` **[String]** unit to append to css values (only appended if values are numeric)\n- `opts.tail` **[String]** string to append after selector\n- `opts.join` **[String]** string to join abbreviation and value in selector\n- `opts.selector` **[Function]** css selector template function\n- `opts.transform` **[Function]** value transform function\n- `opts.parent` **[String]** global parent selector\n\n## Examples\n\nThese examples are primarily to demonstrate how options are used to generate a wide variety of css utilities. They are not necessarily very useful css utilities themselves.\n\n---\n\nMost basic, single `prop` and single `vals`\n\n```js\nvar css = util({\n  prop: 'opacity',\n  vals: 0\n})\n```\n\n```css\n.op0{opacity:0}\n```\n\n---\n\nUse an array as `prop` and `vals`, as well as define `unit`. Notice how floating point values are sanitized in generated selector (decimal replaced with hyphen), and how unit is not appended to a value of 0.\n\n```js\nvar css = util({\n  prop: [\n    'margin',\n    'padding'\n  ],\n  vals: [\n    0,\n    0.5,\n    1\n  ],\n  unit: 'rem'\n})\n```\n\n```css\n.m0{margin:0}\n.m0-5{margin:0.5rem}\n.m1{margin:1rem}\n.p0{padding:0}\n.p0-5{padding:0.5rem}\n.p1{padding:1rem}\n```\n\n---\n\nUse an object as `prop` and `vals` in order to override generated abbreviations. Define `join` to add things like hyphens to selectors.\n\n```js\nvar css = util({\n  prop: {\n    bgc: 'background-color'\n  },\n  vals: {\n    red: '#f00'\n  },\n  join: '-'\n})\n```\n\n```css\n.bgc-red{background-color:#f00}\n```\n\n---\n\nUse a nested array as `prop` in order to generate rules with multiple properties. Notice how [kebab-case](https://softwareengineering.stackexchange.com/questions/104468/if-this-is-camelcase-what-is-this) properties are abbreviated in selector.\n\n```js\nvar css = util({\n  prop: [\n    ['margin-left', 'margin-right']\n  ],\n  vals: 1,\n  unit: 'rem'\n})\n```\n\n```css\n.mlmr1{margin-left:1rem;margin-right:1rem}\n```\n\n---\n\nUse an array which contains both strings and key/val objects as `prop` in order to override only specific abbreviations.\n\n```js\nvar css = util({\n  prop: [ \n    'margin',\n    'margin-right',\n    'margin-left',\n    { mx: ['margin-left', 'margin-right'] }\n  ],\n  vals: 1,\n  unit: 'rem'\n})\n```\n\n```css\n.m1{margin:1rem}\n.mr1{margin-right:1rem}\n.ml1{margin-left:1rem}\n.mx1{margin-left:1rem;margin-right:1rem}\n```\n\n---\n\nDo the same as previous example with `vals` as well.\n\n```js\nvar css = util({\n  prop: {\n    x: 'flex-wrap'\n  },\n  vals: [\n    'wrap',\n    'wrap-reverse',\n    { wn: 'nowrap' }\n  ]\n})\n```\n\n```css\n.xw{flex-wrap:wrap}\n.xwr{flex-wrap:wrap-reverse}\n.xwn{flex-wrap:nowrap}\n```\n\n---\n\nPass a function to `selector` in order to create selectors other than class selectors. Function receives the generated *selector name* as input and should return a [css selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) as a string.\n\n```js\nvar css = util({\n  prop: 'display',\n  vals: 'block',\n  selector: s =\u003e `[data-util~=\"${s}\"]`\n})\n```\n\n```css\n[data-util~=\"db\"]{display:block}\n```\n\n---\n\nUse `modifiers` in order to generate rules for things like [pseudo-classes](https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes), [pseudo-elements](https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-elements), and [descendant selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/Descendant_selectors). Exceptionally useful for hover states.\n\n```js\nvar css = util({\n  prop: 'text-transform',\n  vals: [\n    'uppercase',\n    'lowercase'\n  ],\n  modifiers: [\n    ':hover',\n    ':active',\n    { foc: ':focus' }\n  ]\n})\n```\n\n```css\n.ttu-h:hover{text-transform:uppercase}\n.ttu-a:active{text-transform:uppercase}\n.ttu-foc:focus{text-transform:uppercase}\n.ttl-h:hover{text-transform:lowercase}\n.ttl-a:active{text-transform:lowercase}\n.ttl-foc:focus{text-transform:lowercase}\n```\n\nPassing `false` to modifiers generates rules without a modifier. This is useful for concisely creating sets of rules:\n\n```js\nvar css = util({\n  prop: { fc: 'color' },\n  vals: [\n    'red',\n    'blue',\n    'green'\n  ],\n  modifiers: [\n    false,\n    ':hover'\n  ]\n})\n```\n\n```css\n.fcr{color:red}\n.fcr-h:hover{color:red}\n.fcb{color:blue}\n.fcb-h:hover{color:blue}\n.fcg{color:green}\n.fcg-h:hover{color:green}\n```\n\n---\n\nUse `tail` in order to append an arbitrary string to a selector. Useful when adding things like pseudo-classes which do not need a modifier in the classname.\n\n```js\nvar css = util({\n  raw: {\n    cf: 'content:\"\";display:block;clear:both'\n  },\n  tail: ':after'\n})\n```\n\n```css\n.cf:after{content:\"\";display:block;clear:both}\n```\n\n---\n\nUse `transform` in order to transform values as they are placed into declarations. Useful for things like columns:\n\n```js\nvar css = util({\n  prop: {\n    c: 'width'\n  },\n  vals: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],\n  unit: '%',\n  transform: i =\u003e (i / 12) * 100\n})\n```\n\n```css\n.c1{width:8.333333333333332%}\n.c2{width:16.666666666666664%}\n.c3{width:25%}\n.c4{width:33.33333333333333%}\n.c5{width:41.66666666666667%}\n.c6{width:50%}\n.c7{width:58.333333333333336%}\n.c8{width:66.66666666666666%}\n.c9{width:75%}\n.c10{width:83.33333333333334%}\n.c11{width:91.66666666666666%}\n.c12{width:100%}\n```\n\n---\n\nUse `parent` in order to namespace your rules. Useful for conditional utilities:\n\n```js\nvar css = util({\n  prop: { fc: 'color' },\n  vals: [\n    'red',\n    'blue',\n    'green'\n  ],\n  modifiers: ':hover',\n  parent: '.no-touch'\n})\n```\n\n```css\n.no-touch .fcr-h:hover{color:red}\n.no-touch .fcb-h:hover{color:blue}\n.no-touch .fcg-h:hover{color:green}\n```\n\n## Why\n\nProvides consistency and flexibility when generating functional css utility systems, such as [gr8](https://github.com/jongacnik/gr8).\n\n## Todo\n\n- [ ] Defaults\n- [ ] Assertions\n\n## See Also\n\n- [gr8](https://github.com/jongacnik/gr8)\n\n## License\n\n[MIT](https://github.com/jongacnik/gr8-util/blob/master/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjongacnik%2Fgr8-util","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjongacnik%2Fgr8-util","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjongacnik%2Fgr8-util/lists"}