{"id":18941760,"url":"https://github.com/bahrus/carbon-copy","last_synced_at":"2025-04-15T20:32:10.451Z","repository":{"id":55798390,"uuid":"99500151","full_name":"bahrus/carbon-copy","owner":"bahrus","description":"Copy an HTML template into a DOM node.","archived":false,"fork":false,"pushed_at":"2023-03-04T02:40:48.000Z","size":594,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"baseline","last_synced_at":"2024-10-03T02:15:42.425Z","etag":null,"topics":["custom-element","custom-elements","customelement","referenced-template","shadow-dom","template-instantiation","webcomponent","webcomponents"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/bahrus.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-08-06T16:45:28.000Z","updated_at":"2021-12-13T11:24:33.000Z","dependencies_parsed_at":"2024-11-08T12:31:09.030Z","dependency_job_id":"e83f2439-32ea-4ad4-afa9-cf1363c32ad1","html_url":"https://github.com/bahrus/carbon-copy","commit_stats":{"total_commits":392,"total_committers":2,"mean_commits":196.0,"dds":"0.0025510204081632404","last_synced_commit":"5d28633ea91313129d919ac71ad9b4340755cc59"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bahrus%2Fcarbon-copy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bahrus%2Fcarbon-copy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bahrus%2Fcarbon-copy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bahrus%2Fcarbon-copy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bahrus","download_url":"https://codeload.github.com/bahrus/carbon-copy/tar.gz/refs/heads/baseline","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249148058,"owners_count":21220469,"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":["custom-element","custom-elements","customelement","referenced-template","shadow-dom","template-instantiation","webcomponent","webcomponents"],"created_at":"2024-11-08T12:29:21.480Z","updated_at":"2025-04-15T20:32:10.114Z","avatar_url":"https://github.com/bahrus.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Published on webcomponents.org](https://img.shields.io/badge/webcomponents.org-published-blue.svg)](https://www.webcomponents.org/element/bahrus/carbon-copy)\n\n\u003ca href=\"https://nodei.co/npm/carbon-copy/\"\u003e\u003cimg src=\"https://nodei.co/npm/carbon-copy.png\"\u003e\u003c/a\u003e\n\nb-c-c size:\n\n\u003cimg src=\"http://img.badgesize.io/https://unpkg.com/carbon-copy@0.1.43/build/ES6/b-c-c.iife.js?compression=gzip\"/\u003e\n\nc-c size:\n\n\u003cimg src=\"http://img.badgesize.io/https://unpkg.com/carbon-copy@0.1.43/build/ES6/carbon-copy.js?compression=gzip\"/\u003e\n\n# \\\u003ccarbon-copy\\\u003e\n\n**NB:** These components work best in a [futuristic](https://github.com/bahrus/templ-mount) HTML-friendly world.  In the meantime, they may work best with the help of [one](https://www.npmjs.com/package/html-include-element) [of](https://www.webcomponents.org/element/@github/include-fragment-element) [these](https://www.npmjs.com/package/@vanillawc/wc-include).\n\nCopy a template inside a DOM node. \n\n## b-c-c\n\nFor basic functionality, reference carbon-copy/b-c-c.js and use element name:  b-c-c.  It just clones the source template into the shadowDOM or innerHTML of the element (depending on the value of the noshadow attribute).\n\nSyntax:\n\n```html\n\u003ctemplate id=\"no-matter\"\u003eNo matter what we\n    \u003cslot name=\"verb1\"\u003e\u003c/slot\u003e (no matter what we \u003cslot name=\"verb2\"\u003e\u003c/slot\u003e)\n\u003c/template\u003e\n...\n\u003cb-c-c copy from=\"/no-matter\"\u003e\n    \u003cspan slot=\"verb1\"\u003e\n        do\n    \u003c/span\u003e\n    \u003cspan slot=\"verb2\"\u003e\n        say\n    \u003c/span\u003e\n\u003c/b-c-c\u003e\n```\n\nNote the use of the attribute \"copy\".  This attribute/property makes the tag more readable, but also acts as an \"if\" logical operator.  If attribute/property \"copy\" is present/true, only then will it clone the contents of the referenced template (based on id).  \n\nThe copy property is reflected via the data-copy-is attribute (\"true\"/\"false\"),except on browsers that support custom pseudostate.  This attribute/state can be used for styling.\n\nIn short, b-c-c can be used as a kind of basic \"Reverse Polish Notation\" version of Polymer's [dom-if](https://polymer-library.polymer-project.org/2.0/docs/devguide/templates#dom-if).\n\nIf the attribute \"from\" changes, b-c-c will blow away what was there before, and clone in the new template.  [c-c, on the other hand, will preserve the existing inner (Shadow) DOM, and make it get hidden via display:none.  If the value of \"/from\" reverts back, that original DOM will be re-rendered (and the last template hidden).  c-c can be used, combined with templ-mount, to provide an alternative to Polymer's iron-pages, with no legacy dependencies. Subject to change]\n\nTemplates can come from outside any shadow DOM if the value of \"from\" starts with a slash.  If \"from\" starts with \"./\", the search for the matching template is done within the shadow DOM of the (b-)c-c element (or outside any ShadowDOM if the (b-)c-c element is outside any ShadowDOM).  If from starts with \"../\" then the search is done one level up, etc.\n\nAt each stage, if a host web component is hosting the shadowDOM, and it has a property with the list case of the id, then that property is assumed to reference an HTMLTemplateElement.  This allows hosting web components to inject the property template dynamically.\n\nBy default, b-c-c will copy in the referenced template into a Shadow DOM snippet.  However, if you prefer it copy straight into innerHTML, add attribute / property \"noshadow.\"  Doing so will, of course, eliminate the slot mechanism from functioning.  Hopefully, if template instantiation becomes a thing, that will provide an alternative for this scenario, in terms of declarative support for dynamic content. \n\nIn the meantime / in addition, b-c-c supports two additional properties for adjusting the content dynamically:\n\nIf toBeTransformed/to-be-transformed property/attribute is set, then b-c-c won't append the clone, until a trans-render context object is passed in to property trContext.\n\n## Templatize a materialized DOM element\n\nb-c-c can not only be used to instantiate a template (repeatedly), but also an already materialized DOM element.  It does this by creating a template copy of that DOM element first, and then cloning.  Subsequent copies from the same DOM element will derive from the template copy (so if the DOM element mutates, copies won't see that).\n\n[b-c-c demo](https://jsfiddle.net/bahrus/t0n9eLuo/2/)\n\n## Sample Markup of b-c-c\n\n\u003cdetails\u003e\n    \u003csummary\u003eMarkup\u003c/summary\u003e\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml lang=\"en\"\u003e\n\u003chead\u003e\n    \u003cmeta charset=\"UTF-8\"\u003e\n    \u003cmeta http-equiv=\"X-UA-Compatible\" content=\"IE=edge\"\u003e\n    \u003cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\"\u003e\n    \u003ctitle\u003eDocument\u003c/title\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003cdiv\u003e\n        \u003cstyle\u003e\n          div {\n            background-color: cornsilk;\n          }\n        \u003c/style\u003e\n    \n        \u003ch3\u003e\u003ca href=\"https://www.youtube.com/watch?v=eAfyFTzZDMM\" target=\"_blank\"\u003eBeautiful\u003c/a\u003e\u003c/h3\u003e\n        \u003ch4\u003eChristina Aguilera\u003c/h4\u003e\n        \u003ctemplate id=\"no-matter\"\u003e\n          \u003cstyle\u003e\n            :host {\n              background-color: blanchedalmond;\n            }\n          \u003c/style\u003e\n          No matter what we \u003cslot name=\"verb1\"\u003e\u003c/slot\u003e (no matter what we \u003cslot name=\"verb2\"\u003e\u003c/slot\u003e)\n        \u003c/template\u003e\n        \u003ctemplate id=\"beautiful\"\u003e\n          \u003cstyle\u003e\n            div {\n              background-color: burlywood;\n            }\n          \u003c/style\u003e\n          \u003cdiv\u003e\n            \u003cslot name=\"subjectIs\"\u003e\u003c/slot\u003e beautiful\n          \u003c/div\u003e\n        \u003c/template\u003e\n        \u003ctemplate id=\"down\"\u003e\n          \u003cdiv\u003eSo don't you bring me down today\u003c/div\u003e\n        \u003c/template\u003e\n        \u003ctemplate id=\"chorus\"\u003e\n          \u003cstyle\u003e\n            div {\n              background-color: paleturquoise;\n            }\n          \u003c/style\u003e\n          \u003cb-c-c copy from=\"/beautiful\"\u003e\n            \u003cspan slot=\"subjectIs\"\u003e\n              \u003cslot name=\"subjectIs1\"\u003e\u003c/slot\u003e\n            \u003c/span\u003e\n          \u003c/b-c-c\u003e\n          \u003cdiv\u003eNo matter what they say\u003c/div\u003e\n          \u003cdiv prop-pronoun\u003eWords\n            \u003cslot name=\"verb1\"\u003e\u003c/slot\u003e bring\n            \u003cslot name=\"pronoun1\"\u003e\u003c/slot\u003e down\u003c/div\u003e\n          \u003cdiv\u003eOh no\u003c/div\u003e\n          \u003cb-c-c copy from=\"/beautiful\"\u003e\n            \u003cspan slot=\"subjectIs\"\u003e\n              \u003cslot name=\"subjectIs2\"\u003e\u003c/slot\u003e\n            \u003c/span\u003e\n          \u003c/b-c-c\u003e\n          \u003cdiv\u003eIn every single way\u003c/div\u003e\n          \u003cdiv prop-pronoun\u003eYes words\n            \u003cslot name=\"verb2\"\u003e\u003c/slot\u003e bring\n            \u003cslot name=\"pronoun2\"\u003e\u003c/slot\u003e down\u003c/div\u003e\n          \u003cdiv\u003eOh no\u003c/div\u003e\n          \u003cb-c-c copy from=\"/down\"\u003e\u003c/b-c-c\u003e\n        \u003c/template\u003e\n\n        \u003cp\u003eDon't look at me\u003c/p\u003e\n        \u003cp\u003e\n          \u003cdiv\u003eEveryday is so wonderful\u003c/div\u003e\n          \u003cdiv\u003eThen suddenly\u003c/div\u003e\n          \u003cdiv\u003eIt's hard to breathe\u003c/div\u003e\n          \u003cdiv\u003eNow and then I get insecure\u003c/div\u003e\n          \u003cdiv\u003eFrom all the pain\u003c/div\u003e\n          \u003cdiv\u003eI'm so ashamed\u003c/div\u003e\n        \u003c/p\u003e\n        \u003cp\u003e\n          \u003cb-c-c copy from=\"/chorus\"\u003e\n    \n            \u003cspan slot=\"verb1\"\u003ecan't\u003c/span\u003e\n            \u003cspan slot=\"verb2\"\u003ecan't\u003c/span\u003e\n            \u003cspan slot=\"pronoun1\"\u003eme\u003c/span\u003e\n            \u003cspan slot=\"pronoun2\"\u003eme\u003c/span\u003e\n            \u003cspan slot=\"subjectIs1\"\u003eI am\u003c/span\u003e\n            \u003cspan slot=\"subjectIs2\"\u003eI am\u003c/span\u003e\n          \u003c/b-c-c\u003e\n        \u003c/p\u003e\n        \u003cp\u003e\n    \n          \u003cdiv\u003eTo all your friends you're delirious\u003c/div\u003e\n          \u003cdiv\u003eSo consumed\u003c/div\u003e\n          \u003cdiv\u003eIn all your doom, ooh\u003c/div\u003e\n          \u003cdiv\u003eTrying hard to fill the emptiness\u003c/div\u003e\n          \u003cdiv\u003eThe pieces gone\u003c/div\u003e\n          \u003cdiv\u003eLeft the puzzle undone\u003c/div\u003e\n          \u003cdiv\u003eAin't that the way it is\u003c/div\u003e\n        \u003c/p\u003e\n        \u003cp\u003e\n          \u003cb-c-c copy from=\"/chorus\"\u003e\n            \u003cspan slot=\"verb1\"\u003ecan't\u003c/span\u003e\n            \u003cspan slot=\"verb2\"\u003ecan't\u003c/span\u003e\n            \u003cspan slot=\"pronoun1\"\u003eyou\u003c/span\u003e\n            \u003cspan slot=\"pronoun2\"\u003eyou\u003c/span\u003e\n            \u003cspan slot=\"subjectIs1\"\u003eYou are\u003c/span\u003e\n            \u003cspan slot=\"subjectIs2\"\u003eYou are\u003c/span\u003e\n          \u003c/b-c-c\u003e\n        \u003c/p\u003e\n        \u003cbr\u003e\n        \u003cb-c-c copy from=\"/no-matter\"\u003e\n          \u003cspan slot=\"verb1\"\u003edo\u003c/span\u003e\n          \u003cspan slot=\"verb2\"\u003edo\u003c/span\u003e\n        \u003c/b-c-c\u003e\n        \u003cbr\u003e\n        \u003cb-c-c copy from=\"/no-matter\"\u003e\n          \u003cspan slot=\"verb1\"\u003esay\u003c/span\u003e\n          \u003cspan slot=\"verb2\"\u003esay\u003c/span\u003e\n        \u003c/b-c-c\u003e\n        \u003cdiv\u003eWe're the song inside the tune (yeah, oh yeah)\u003c/div\u003e\n        \u003cdiv\u003eFull of beautiful mistakes\u003c/div\u003e\n        \u003cp\u003e\n          \u003cdiv\u003eAnd everywhere we go (and everywhere we go)\u003c/div\u003e\n          \u003cdiv\u003eThe sun will always shine (the sun will always, always, shine)\u003c/div\u003e\n          \u003cdiv\u003eAnd tomorrow we might awake\u003c/div\u003e\n          \u003cdiv\u003eOn the other side\u003c/div\u003e\n        \u003c/p\u003e\n        \u003cp\u003e\n          \u003cb-c-c copy from=\"/chorus\"\u003e\n            \u003cspan slot=\"verb1\"\u003ewon't\u003c/span\u003e\n            \u003cspan slot=\"verb2\"\u003ecan't\u003c/span\u003e\n            \u003cspan slot=\"pronoun1\"\u003eus\u003c/span\u003e\n            \u003cspan slot=\"pronoun2\"\u003eus\u003c/span\u003e\n            \u003cspan slot=\"subjectIs1\"\u003eWe are\u003c/span\u003e\n            \u003cspan slot=\"subjectIs2\"\u003eWe are\u003c/span\u003e\n          \u003c/b-c-c\u003e\n        \u003c/p\u003e\n        \u003cp\u003e\n          \u003cdiv\u003eOh, oh\u003c/div\u003e\n          \u003cdiv\u003eDon't you bring me down today\u003c/div\u003e\n          \u003cdiv\u003eDon't you bring me down, ooh\u003c/div\u003e\n          \u003cdiv\u003eToday\u003c/div\u003e\n        \u003c/p\u003e\n    \n      \u003c/div\u003e\n      \u003cscript type=module src=\"https://unpkg.com/carbon-copy@0.1.53/b-c-c.js?module\"\u003e\u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n\u003c/details\u003e\n\n## c-c -- Codeless Web Components\n\nFor more extended functionality, use element c-c, \"codeless component\" (reference:  carbon-copy/c-c.js).  \n\nUnlike b-c-c, c-c actually generates a custom (web) component on the fly, based on the id of the template.  If the template is a simple word, like \"mytemplate\" the generated custom element will have name c-c-mytemplate.  If the id has a dash in it, it will create a custom element with that name (so id's are limited to what is allowed in terms of custom element names).   \n\nSo here are the steps to create a web component using c-c:\n\nStep 1.  Define a template:\n\n```html\n\u003ctemplate id=\"hello-world\"\u003e\n    Hello, world\n\u003c/template\u003e\n```\n\nStep 2.  Register the web component\n\n```html\n\u003cc-c copy from=\"/hello-world\"\u003e\u003c/c-c\u003e\n```\n\nOr, if the c-c element comes right after the template element:\n\n```html\n\u003ctemplate id=\"hello-world\"\u003e\n    Hello, world\n\u003c/template\u003e\n\u003cc-c copy from-prev-sibling\u003e\u003c/c-c\u003e\n```\n\nStep 3.  Add your web component to the page\n\n```html\n\u003cbody\u003e\n  ...\n    \u003chello-world\u003e\u003c/hello-world\u003e\n  ...\n\u003c/body\u003e\n```\n\nStep 4.  Stare into the abyss. \n\n### Adding string/numeric/bool properties to your declarative web component\n\nThe template can specify a list of primitive properties to add to the automatically generated web component:\n\n```html\n\u003ctemplate id=\"pow\"\u003e\n    \u003cdiv\u003e\n        \u003cslot name=\"subjectIs\"\u003e\u003c/slot\u003e \n    \u003c/div\u003e\n\u003c/template\u003e\n...\n\u003cc-c from =\"/pow\" string-props='[\"name\",\"rank\", \"serialNumber\"]' num-props='[\"age\", \"weight\"]' bool-props='[\"mia\"]'\u003e\n```\n\nThese properties can be read via attributes on the \"c-c-pow\" element instances (in this example), or passed in as properties.  They will reflect to [custom psuedo states](https://www.chromestatus.com/feature/6537562418053120) when the browser allows it.\n\n\n### Bind to the properties\n\nc-c (or carbon-copy) supports binding to the UI using an [extension](https://www.npmjs.com/package/templ-arts) of Github's [Template-Parts library](https://github.com/github/template-parts/).\n\nExample:\n\n```html\n\u003ctemplate id=hello-world\u003e\n    \u003cdiv\u003eHello, {{place}}\u003c/div\u003e\n\u003c/template\u003e\n\u003cc-c copy from=\"/hello-world\" string-props='[\"place\"]'\u003e\u003c/c-c\u003e\n\n\u003chello-world place=\"mars\"\u003e\u003c/hello-world\u003e\n```\n\nResults in displaying \"Hello mars\".\n\nThe value of place can be manipulated either via the attribute value or the property value.  Lisp-case/camelCase is used for attributes/properties.\n\n[Demo](https://jsfiddle.net/bahrus/t0n9eLuo/4/)\n\nSetting default values\n\n```html\n\u003ctemplate id=hello-world\u003e\n    \u003cdiv\u003eHello, {{place}}\u003c/div\u003e\n\u003c/template\u003e\n\u003cc-c copy from=\"/hello-world\" string-props='[\"place=World\"]'\u003e\u003c/c-c\u003e\n\n\u003chello-world place=\"mars\"\u003e\u003c/hello-world\u003e\n```\n\n### Attaching event handlers\n\nUse [on-to-me](https://github.com/bahrus/on-to-me) [or](https://github.com/bahrus/pass-down) [other](https://github.com/bahrus/p-et-alia) [declarative](https://github.com/bahrus/xtal-decor) vocabulary libraries.\n\n## carbon-copy [TODO]\n\nFinally we get to element carbon-copy.  It synthesizes some of the features of both b-c-c and c-c together.\n\nLike b-c-c, it can take a materialized DOM element as its input, not just a template.  Like b-c-c, it can perform a transform on the (materialized) DOM fragment.\n\nThis transformed fragment can become the template used for generating the custom element.  The transform can be used to insert dynamic \"parts\" in the template.\n\nSo while c-c encourages a 100% JS-free web component, with not much support for SSR, carbon-copy allows an initial view based on SSR, but then it transforms the initial view into a general template used by web component instances.\n\n\n\n\u003c!--### Adding Object Properties [TODO]\n\n```html\n\u003ctemplate id=\"beautiful\" data-obj-props=\"d,e\"\u003e\n    \u003cdiv\u003e\n        \u003cslot name=\"subjectIs\"\u003e\u003c/slot\u003e beautiful\n    \u003c/div\u003e\n\u003c/template\u003e\n```\n\nObject properties also observe attribute changes with the same name as the property, and also calls onPropsChange.\n\nIf you set the attribute value for an object property, it will assume the string is JSON (surrounded by single quotes), and will parse it.\n\nChanges to object properties fire events with the name \"[name of prop]-changed\".--\u003e\n\n## Viewing Your Element Locally\n\n1.  Install node.\n2.  Clone or for fork this git repo.\n3.  In a command prompt from the folder of this git repo:\n\n```\n$ npm run serve\n```\n\n4.  Open browser to http://localhost/demo.\n\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbahrus%2Fcarbon-copy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbahrus%2Fcarbon-copy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbahrus%2Fcarbon-copy/lists"}