{"id":23280981,"url":"https://github.com/nicholaswmin/css-gridpaper","last_synced_at":"2025-04-06T13:35:40.958Z","repository":{"id":265406310,"uuid":"890234430","full_name":"nicholaswmin/css-gridpaper","owner":"nicholaswmin","description":"simple, adaptive typographic grid ","archived":false,"fork":false,"pushed_at":"2024-11-18T08:53:08.000Z","size":29,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-29T02:47:05.465Z","etag":null,"topics":["grid","typography","user-interface-design"],"latest_commit_sha":null,"homepage":"https://nicholaswmin.github.io/css-gridpaper/","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/nicholaswmin.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":"2024-11-18T08:18:37.000Z","updated_at":"2024-11-18T23:55:01.000Z","dependencies_parsed_at":"2024-11-29T08:45:17.588Z","dependency_job_id":"22a2f0f5-6a00-41ce-8d8a-950ae12f4b39","html_url":"https://github.com/nicholaswmin/css-gridpaper","commit_stats":null,"previous_names":["nicholaswmin/css-gridpaper"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicholaswmin%2Fcss-gridpaper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicholaswmin%2Fcss-gridpaper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicholaswmin%2Fcss-gridpaper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicholaswmin%2Fcss-gridpaper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nicholaswmin","download_url":"https://codeload.github.com/nicholaswmin/css-gridpaper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247489300,"owners_count":20947086,"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":["grid","typography","user-interface-design"],"created_at":"2024-12-19T23:39:50.383Z","updated_at":"2025-04-06T13:35:40.913Z","avatar_url":"https://github.com/nicholaswmin.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![tests:unit](https://github.com/nicholaswmin/css-gridpaper/actions/workflows/tests:unit.yml/badge.svg)](https://github.com/nicholaswmin/css-gridpaper/actions/workflows/tests:unit.yml)\n\n`\u003ccss-gridpaper\u003e`\n\nDraws an adaptive grid as a page background.\n\nIt's a pixel-perfect match of the same grid that [Gridlover][gridlover] \nuses, the modular-scale/vertical-rhythm design tool.  \nI use it to tweak vertical-rhythm formulas.\n\nIt [redraws automatically](#redrawing-the-grid), \ndepending on use-case.\n\n## install\n\n```bash\nnpm i https://github.com/nicholaswmin/css-gridpaper.git\n```\n\n### quickstart\n\nIt's a native [WebComponent][wc] with 0 dependencies.\n\nSo, assuming you have an `.html` doc:\n\n```html\n\u003cscript type=\"module\"\u003e import 'css-gridpaper' \u003c/script\u003e\n\n\u003cstyle\u003e\n  :root {\n    --base-size: 16px;\n    --line-height: 1.5\n  }\n\n  body { \n    font-size: var(--base-size); \n    line-height: var(--line-height);\n  }\n\u003c/style\u003e\n\n\u003ccss-gridpaper \n  size-prop=\"--base-size\" \n  scale-prop=\"--line-height\"\n  color=\"rgba(0, 120, 180, 0.2)\"\u003e\n\u003c/css-gridpaper\u003e\n\n\u003c!-- Rest of your HTML --\u003e\n```\n\u003e note: The DOM position doesn't matter. \n\nTrigger a redraw grid if you update the CSS variables:\n\n\u003e **note:** you might [not need this](#redrawing-the-grid).\n\n```js\n// set --base-size to: 20\ndocument.documentElement.style.setProperty('--base-size', 20)\n\n// redraw grid to new variables\ndocument.querySelector('css-gridpaper').draw()\n```\n\nThere's 2 ways to draw the grid:\n\n1. Using [CSS variables][css-custom].\n    This is what Gridlover does \u0026 what's reasonable to be doing because it \n    adapts to `font-size` and `line-height`. \n    Read below for more.\n2. [Manual redraw](#manual-redraw), using `element.draw(size)`. \n    Almost pointless but it's there.\n\n## setting up CSS variables\n\nThe grid size is calculated via 2 [CSS variables][css-custom].\nIt expects that you've defined them in a `.css` somewhere:\n\n- a `size` property, type numeric.\n- a `scale` property, type numeric. \n\nThe name is configurable, so `size` can be i.e: `--base-size: 10`. \n\nThe grid is drawn as `size * scale`.\n\nHere's my example:\n\n```css\n: root {\n    --base-size: 20; /* my size prop */\n    --line-height: 1.5 /* my scale prop */\n}\n```\n\n... `\u003ccss-gridpaper\u003e` is defined in your HTML as:\n\n```html\n\u003cstyle\u003e\n  :root {\n    --base-size: 30;\n    --line-height: 1.5\n  }\n\u003c/style\u003e\n\n\u003cp\u003e More HTML elements ... \u003c/p\u003e\n\n\u003ccss-gridpaper \n    size-prop=\"--base-size\" \n    scale-prop=\"--line-height\"\n    color=\"rgba(0, 119, 179, 0.4)\"\u003e\n\u003c/css-gridpaper\u003e\n\n\u003cscript type=\"module\"\u003e import 'css-gridpaper' \u003c/script\u003e\n```\n... this draws a grid of `30px` vertical intervals, \nas the `background` of `document.body`.\n\n\u003e Yes, thats a side-effect but nobody cares. \n\u003e It's hassle-free and precise.  \n\u003e\n\u003e That's exactly what Gridlover does anyway.\n\n\n### redrawing the grid\n\nA grid that doesn't adapt to the `font-size` or `line-height` isn't helpful.  \nYou (most probably) need to redraw the grid when these values change.\n\nThe element listens for `change` and `input` events on `window`,\nwhich triggers a redraw.\n\nIt assumes you used some kind of input i.e `\u003cinput type=range\u003e\"` to tweak some \nvalues, hence why that event bubbled up to `window`. \n\nI use sliders to tweak my layouts or formulas and this assumption \nmakes for 0-hassle setups.\n\nIf you do something similar, the grid redraw would work out-the-box \nfor you too. You can specify the events it listens or at the worst-case,\ntrigger a redraw manually.\n\n### manual redraw\n\nThe following API redraws manually.\n\n- `element.draw()` triggers a redraw using the CSS variables.\n- `element.draw(50)` triggers a redraw with an explicit value.\n  You can skip declaring CSS variables in this case but you must\n  declare `manual` as an attribute, as shown below:\n\n```html\n\u003ccss-gridpaper manual\u003e\u003c/css-gridpaper\u003e\n\n\u003cscript type=\"module\"\u003e \n  import 'css-gridpaper'\n\n  // draw a 30px grid\n  document.querySelector('css-gridpaper').draw(30)\n\u003c/script\u003e\n```\n\n### listen for specific events\n\nDeclare a comma-separated list of event names on the `on-events` attribute, \nwhich *overrides* the events its listening for. \n\nOr disable entirely by passing an empty string.\n\nIn the example below, the button is not connected to the element at all. \nClicking the button fires `click` events, it's a button after all and the \nclick events bubble up on `window` where our elements picks it up and redraws.\n\n```html\n\u003cbutton\u003eRedraw\u003c/button\u003e\n\n\u003ccss-gridpaper \n  on-events=\"click,input\"\n  size-prop=\"--base-size\" \n  scale-prop=\"--line-height\"\n  color=\"rgba(0, 119, 179, 0.4)\"\u003e\n\u003c/css-gridpaper\u003e\n\n\u003cscript type=\"module\"\u003e\n  import 'css-gridpaper'\n\u003cscript\u003e\n```\n\n\u003e Note: Unless the CSS variables `size` or `scale` have changed, \nyou won't notice anything since it redraws the same grid. duh.\n\nActually I lied, you don't even need a `button`. \nJust click with your mouse anywhere, it still works.\n\n## gotchas\n\nThe attributes don't update after 1st initialisation.\n\nI don't need it so I didnt bother but if you do, \nPRs are always welcome.\n\n## test \n\n```bash\nnpm i \nnode --run test\n```\n\n## serve for dev. \n\n```bash\nnode --run start\n```\n\n## authors\n\n[@nicholaswmin][nicholaswmin]\n\n## license \n\n\u003e Copyright 2024\n\u003e\n\u003e Nicholas Kyriakides, @nicholaswmin\n\u003e The MIT License\n\u003e\n\u003e Permission is hereby granted, free of charge, to any person obtaining a copy \n\u003e of this software and associated documentation files (the “Software”), to deal \n\u003e in the Software without restriction, including without limitation the rights \n\u003e to use, copy, modify, merge, publish, distribute, sublicense, and/or sell \n\u003e copies of the Software, and to permit persons to whom the Software is \n\u003e furnished to do so, subject to the following conditions:\n\u003e\n\u003e The above copyright notice and this permission notice shall be included in all \n\u003e copies or substantial portions of the Software.\n\n\n[gridlover]: https://gridlover.net\n[nicholaswmin]: https://github.com/nicholaswmin\n[wc]: https://developer.mozilla.org/en-US/docs/Web/API/Web_components\n[css-custom]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicholaswmin%2Fcss-gridpaper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnicholaswmin%2Fcss-gridpaper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicholaswmin%2Fcss-gridpaper/lists"}