@octaviaflow/icon-helpers 1.0.0

package/README.md

@@ -0,0 +1,117 @@
+# @octaviaflow/icon-helpers
+
+> Helpers used alongside icons for digital and software products using the
+> Carbon Design System
+
+## Getting started
+
+To install `@octaviaflow/icon-helpers` in your project, you will need to run the
+following command using [npm](https://www.npmjs.com/):
+
+```bash
+npm install -S @octaviaflow/icon-helpers
+```
+
+If you prefer [Yarn](https://yarnpkg.com/en/), use the following command
+instead:
+
+```bash
+yarn add @octaviaflow/icon-helpers
+```
+
+## Usage
+
+`@octaviaflow/icon-helpers` provides a couple of helpers for rendering `<svg>` nodes
+in a document, or to help get the correct attributes to set on an `<svg>` node.
+These include:
+
+| Name               | Type                              | Description                                                                  |
+| ------------------ | --------------------------------- | ---------------------------------------------------------------------------- |
+| `getAttributes`    | `(attributes: Object) => Object`  | Get the attributes for an `<svg>` node                                       |
+| `formatAttributes` | `(attributes: Object) => String`  | Format the attributes into a string that can be applied to a node in the DOM |
+| `toString`         | `(descriptor: Object) => String`  | Format the given icon descriptor into a string. Useful for templates         |
+| `toSVG`            | `(descriptor: Object) => DOMNode` | Format the given icon descriptor into a DOM node                             |
+
+For most of the methods, `attributes` corresponds with whatever the name and
+value would be if you were writing the HTML for the `<svg>`. For example, if we
+wanted to set `width` and `height` we would do the following:
+
+```js
+const { getAttributes } = require('@octaviaflow/icon-helpers');
+const attributes = getAttributes({ width: 20, height: 20 });
+```
+
+In order for the icon to be considered focusable, you will need to provide
+either `aria-label`, `aria-labelledby`, or `title` in the given `attributes` in
+addition to `tabindex`. For example:
+
+```js
+const { getAttributes } = require('@octaviaflow/icon-helpers');
+const attributes = getAttributes({
+  'aria-label': 'My icon label',
+  tabindex: '0',
+});
+```
+
+### Icon descriptors
+
+An icon descriptor is the term we use to describe icon objects exported by
+`@octaviaflow/icons`. By default, they will have the following shape:
+
+```js
+{
+  elem: 'svg',
+  attrs: {
+    xmlns: 'http://www.w3.org/2000/svg',
+    viewBox: '0 0 16 16',
+    width: 16,
+    height: 16,
+  },
+  content: [
+    {
+      elem: 'path',
+      attrs: {
+        d: '...',
+      },
+    },
+  ],
+  name: 'IconName',
+  size: 16,
+}
+```
+
+You can import these definitions directly from `@octaviaflow/icons` and use them
+alongside `toSVG` or `toString` by doing:
+
+```js
+import { IconName } from '@octaviaflow/icons';
+import { toString, toSVG } from '@octaviaflow/icon-helpers';
+
+const iconString = toString(IconName);
+const iconSVG = toSVG({
+  ...IconName,
+  attrs: {
+    ...IconName.attrs,
+    myCustomAttribute: 'myCustomAttributeValue',
+  },
+});
+```
+
+## 🙌 Contributing
+
+We're always looking for contributors to help us fix bugs, build new features,
+or help us improve the project documentation. If you're interested, definitely
+check out our [Contributing Guide](/.github/CONTRIBUTING.md)! 👀
+
+## 📝 License
+
+Licensed under the [Apache 2.0 License](/LICENSE).
+
+## <picture><source height="20" width="20" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-dark.svg"><source height="20" width="20" media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-light.svg"><img height="20" width="20" alt="IBM Telemetry" src="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-light.svg"></picture> IBM Telemetry
+
+This package uses IBM Telemetry to collect de-identified and anonymized metrics
+data. By installing this package as a dependency you are agreeing to telemetry
+collection. To opt out, see
+[Opting out of IBM Telemetry data collection](https://github.com/ibm-telemetry/telemetry-js/tree/main#opting-out-of-ibm-telemetry-data-collection).
+For more information on the data being collected, please see the
+[IBM Telemetry documentation](https://github.com/ibm-telemetry/telemetry-js/tree/main#ibm-telemetry-collection-basics).

package/es/index.js

@@ -0,0 +1 @@
+var l={focusable:"false",preserveAspectRatio:"xMidYMid meet"};function s({width:n,height:e,viewBox:o=`0 0 ${n} ${e}`,...i}={}){let{tabindex:r,...u}=i,t={...l,...u,width:n,height:e,viewBox:o};return t["aria-label"]||t["aria-labelledby"]||t.title?(t.role="img",r!=null&&(t.focusable="true",t.tabindex=r)):t["aria-hidden"]=!0,t}function a(n){let{elem:e="svg",attrs:o={},content:i=[]}=n,r=i.map(a).join("");return e!=="svg"?`<${e} ${c(o)}>${r}</${e}>`:`<${e} ${c(s(o))}>${r}</${e}>`}function c(n){return Object.keys(n).reduce((e,o,i)=>{let r=`${o}="${n[o]}"`;return i===0?r:e+" "+r},"")}function f(n){let{elem:e="svg",attrs:o={},content:i=[]}=n,r=document.createElementNS("http://www.w3.org/2000/svg",e),u=e!=="svg"?o:s(o);Object.keys(u).forEach(t=>{r.setAttribute(t,o[t])});for(let t=0;t<i.length;t++)r.appendChild(f(i[t]));return r}export{l as defaultAttributes,c as formatAttributes,s as getAttributes,f as toSVG,a as toString};

package/lib/index.cjs

@@ -0,0 +1 @@
+"use strict";var l=Object.defineProperty;var d=Object.getOwnPropertyDescriptor;var p=Object.getOwnPropertyNames;var b=Object.prototype.hasOwnProperty;var g=(r,t)=>{for(var o in t)l(r,o,{get:t[o],enumerable:!0})},$=(r,t,o,i)=>{if(t&&typeof t=="object"||typeof t=="function")for(let e of p(t))!b.call(r,e)&&e!==o&&l(r,e,{get:()=>t[e],enumerable:!(i=d(t,e))||i.enumerable});return r};var A=r=>$(l({},"__esModule",{value:!0}),r);var x={};g(x,{defaultAttributes:()=>m,formatAttributes:()=>u,getAttributes:()=>s,toSVG:()=>a,toString:()=>c});module.exports=A(x);var m={focusable:"false",preserveAspectRatio:"xMidYMid meet"};function s({width:r,height:t,viewBox:o=`0 0 ${r} ${t}`,...i}={}){let{tabindex:e,...f}=i,n={...m,...f,width:r,height:t,viewBox:o};return n["aria-label"]||n["aria-labelledby"]||n.title?(n.role="img",e!=null&&(n.focusable="true",n.tabindex=e)):n["aria-hidden"]=!0,n}function c(r){let{elem:t="svg",attrs:o={},content:i=[]}=r,e=i.map(c).join("");return t!=="svg"?`<${t} ${u(o)}>${e}</${t}>`:`<${t} ${u(s(o))}>${e}</${t}>`}function u(r){return Object.keys(r).reduce((t,o,i)=>{let e=`${o}="${r[o]}"`;return i===0?e:t+" "+e},"")}function a(r){let{elem:t="svg",attrs:o={},content:i=[]}=r,e=document.createElementNS("http://www.w3.org/2000/svg",t),f=t!=="svg"?o:s(o);Object.keys(f).forEach(n=>{e.setAttribute(n,o[n])});for(let n=0;n<i.length;n++)e.appendChild(a(i[n]));return e}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@octaviaflow/icon-helpers",
+  "description": "Helpers used alongside icons for digital and software products using the OctaviaFlow Design System",
+  "version": "1.0.0",
+  "license": "Apache-2.0",
+  "main": "lib/index.cjs",
+  "module": "es/index.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./es/index.js",
+      "require": "./lib/index.cjs"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/octaviaflow-design-system.git",
+    "directory": "packages/icon-helpers"
+  },
+  "bugs": "https://github.com/octaviaflow-design-system/issues",
+  "files": [
+    "es",
+    "lib",
+    "umd",
+    "telemetry.yml"
+  ],
+  "keywords": [
+    "octaviaflow",
+    "icon-helpers",
+    "elements",
+    "components",
+    "react"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@babel/runtime": "^7.25.0",
+    "tslib": "^2.6.0"
+  },
+  "scripts": {
+    "build:es": "esbuild src/index.ts --bundle --minify --outdir=es --target=es2020 --format=esm",
+    "build:cjs": "esbuild src/index.ts --bundle --minify --outdir=lib --target=es2020 --format=cjs --out-extension:.js=.cjs",
+    "build:types": "tsc",
+    "build": "bun run clean && bun run build:es & bun run build:cjs & bun run build:types",
+    "clean": "rimraf es lib umd"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.28.6",
+    "@babel/preset-env": "^7.28.6",
+    "@octaviaflow/cli": "^1.0.0",
+    "esbuild": "^0.27.2",
+    "rimraf": "^6.0.0",
+    "typescript": "^5.9.3",
+    "typescript-config-octaviaflow": "^1.0.0"
+  },
+  "sideEffects": false
+}

package/telemetry.yml

@@ -0,0 +1,17 @@
+# yaml-language-server: $schema=https://unpkg.com/@octaviaflow/telemetry-config-schema@v1.0.0/dist/config.schema.json
+version: 1
+projectId: '56319a6c-7174-4766-850c-59307f0d1fe6'
+name: 'OctaviaFlow Icon Helpers'
+storage:
+  type: 'file'
+  file:
+    directory: '/Volumes/Main/Projects/OctaviaFlow-Design-System/telemetry-logs'
+    fileNamePattern: 'octaviaflow-icon-helpers-{timestamp}.json'
+    maxFileSizeMB: 10
+    compress: false
+collect:
+  npm:
+    dependencies: null
+  js:
+    functions: {}
+    tokens: null