@teacss/preset-icons 0.3.0

package/LICENSE

@@ -0,0 +1,22 @@
+# MIT License
+
+Copyright (c) 2021-PRESENT Anthony Fu <https://github.com/antfu>
+Copyright (c) 2026-PRESENT Billgo <hi@billgo.me>
+
+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.

package/README.md

@@ -0,0 +1,97 @@
+# @teacss/preset-icons
+
+**Pure-CSS icon utilities for TeaCSS.**
+
+## Purpose
+
+`@teacss/preset-icons` is the official opt-in icon preset for application
+authors who want Iconify assets compiled from
+`icon:<collection>-<icon-name>` classes. It loads installed, custom, or CDN
+collection data, emits icons as CSS masks or backgrounds, and exposes
+icon-specific merge metadata for custom runtime mergers. The generated icons
+require no client-side runtime script.
+
+This package owns only the icon vocabulary and its loading behavior:
+`@teacss/core` owns parsing and CSS generation,
+`@teacss/preset-standard` supplies general utilities, themes, conditions, and
+preflights, and `@teacss/preset-articles` supplies long-form content styling.
+None of those other preset vocabularies are bundled here.
+
+## Usage
+
+```css
+@preset "standard";
+@preset "icons";
+@teacss;
+```
+
+The `icons` short name works with either the application-facing `teacss`
+package or a direct `@teacss/preset-icons` installation.
+
+```html
+<span class="icon:carbon-sun"></span>
+<span class="icon:carbon-moon@dark"></span>
+```
+
+The only utility grammar is `icon:<collection>-<icon-name>`. The value must
+include its Iconify collection. When collection names overlap, the longest
+known collection prefix determines the split and TeaCSS loads that collection
+only; missing icons do not fall back to a shorter collection name.
+Collection-prefix matching uses the preset's packaged, offline Iconify catalog
+(including `griddy-icons`) plus configured custom names; it does not perform
+runtime catalog discovery.
+
+`mode: "auto"` chooses a mask for `currentColor` icons and a background image
+for multicolor icons. Override one icon with `?mask`, `?bg`, or `?auto`, for
+example `icon:carbon-sun?mask`.
+
+Install the Iconify collections you use, such as `@iconify-json/carbon`. CSS
+integrations also resolve the raw qualified name through `icon(...)`:
+
+```css
+.logo {
+  background-image: icon("carbon-sun");
+}
+```
+
+When configuring `presetIcons()` with `cdn`, `customFetch` can replace the
+default CDN loader. It receives the complete collection URL and must resolve
+to parsed `IconifyJSON` collection data, not a raw `Response` object.
+
+Programmatic integrations should use the preset's `api.resolveIcon(name)` so
+they share its configured loader and cache. For lower-level composition,
+`parseIconWithLoader()` resolves a qualified name with one loader,
+`createCDNFetchLoader()` creates the CDN step, and `combineLoaders()` composes
+multiple sources.
+
+For runtime class merging, the `/merge` entry exports both a lazy icon-only
+`cn` and the self-contained plugin:
+
+```sh
+bun add @teacss/classes
+```
+
+```ts
+import { createMerger } from "@teacss/classes";
+import {
+  cn as iconCn,
+  pluginIcon,
+} from "@teacss/preset-icons/merge";
+
+const cn = createMerger({ plugins: [pluginIcon] });
+
+iconCn("icon:carbon-sun", "icon:not-real-name"); // "icon:not-real-name"
+```
+
+The application `cn` from `teacss` already composes this plugin with the
+standard vocabulary. The zero-config `cn` from
+`@teacss/preset-standard/merge` remains standard-only. Runtime merging checks
+only the canonical lexical grammar, not whether a collection or icon is
+installed. Canonical nonexistent resources
+merge normally; non-canonical `icon:*` declarations are opaque, so different
+raw strings survive and exact duplicates keep their last position. The bare
+keyword `icon` has no canonical value and is opaque as well.
+
+## Status
+
+Pre-1.0. Icon output follows the installed Iconify collection data.

package/dist/browser.d.ts

@@ -0,0 +1,5 @@
+import { a as parseIconWithLoader, c as ParsedIcon, i as createPresetIcons, n as combineLoaders, o as _default, r as createCDNFetchLoader, s as IconsOptions, t as IconsAPI } from "./core-CmBaHpDm.js";
+//#region src/browser.d.ts
+declare const presetIcons: import("@teacss/core").PresetFactory<object, IconsOptions>;
+//#endregion
+export { IconsAPI, type IconsOptions, type ParsedIcon, combineLoaders, createCDNFetchLoader, createPresetIcons, presetIcons as default, presetIcons, _default as icons, parseIconWithLoader };

package/dist/browser.js

@@ -0,0 +1 @@
+import{a as e,i as t,n,r,t as i}from"./core-By2NcOr9.js";import{t as a}from"./cdn-BAAzT6MS.js";import{loadIcon as o}from"@iconify/utils";const s=r(async e=>{let t=[o],r=e?.customFetch,s=e?.cdn;return r&&s?t.push(n(r,s)):s&&t.push(await a(s)),i(t)});export{i as combineLoaders,n as createCDNFetchLoader,r as createPresetIcons,s as default,s as presetIcons,e as icons,t as parseIconWithLoader};

package/dist/cdn-BAAzT6MS.js

@@ -0,0 +1 @@
+import{n as e}from"./core-By2NcOr9.js";async function t(t){let{$fetch:n}=await import(`ofetch`);return e(e=>n(e),t)}export{t};

package/dist/core-By2NcOr9.js

@@ -0,0 +1 @@
+import{t as e}from"./syntax-DmIPw0tH.js";import{quicklyValidateIconSet as t}from"@iconify/utils";import{definePreset as n,getEnvFlags as r,warnOnce as i}from"@teacss/core";import{searchForIcon as a}from"@iconify/utils/lib/loader/modern";import{encodeSvgForCss as o}from"@iconify/utils/lib/svg/encode-svg-for-css";var s=`academicons.akar-icons.ant-design.arcticons.at-icons.basil.bi.bitcoin-icons.boxicons.bpmn.brandico.bubbles.bx.bxl.bxs.bytesize.carbon.catppuccin.cbi.charm.ci.cib.cif.cil.circle-flags.circum.clarity.codex.codicon.covid.cryptocurrency-color.cryptocurrency.cuida.dashicons.devicon-line.devicon-original.devicon-plain.devicon.dinkie-icons.duo-icons.ei.el.emblemicons.emojione-monotone.emojione-v1.emojione.entypo-social.entypo.eos-icons.ep.et.eva.f7.fa-brands.fa-regular.fa-solid.fa.fa6-brands.fa6-regular.fa6-solid.fa7-brands.fa7-regular.fa7-solid.fad.famicons.fe.feather.file-icons.flag.flagpack.flat-color-icons.flat-ui.flowbite.fluent-color.fluent-emoji-flat.fluent-emoji-high-contrast.fluent-emoji.fluent-mdl2.fluent.fontelico.fontisto.formkit.foundation.fxemoji.gala.game-icons.garden.gcp.geo.gg.ginetex.gis.glyphs-poly.glyphs.gravity-ui.griddy-icons.gridicons.grommet-icons.guidance.healthicons.heroicons-outline.heroicons-solid.heroicons.hugeicons.humbleicons.ic.icomoon-free.icon-park-outline.icon-park-solid.icon-park-twotone.icon-park.iconamoon.iconoir.icons8.il.ion.iwwa.ix.jam.la.lets-icons.line-md.lineicons.logos.ls.lsicon.lucide-lab.lucide.mage.majesticons.maki.map.marketeq.material-icon-theme.material-symbols-light.material-symbols.mdi-light.mdi.medical-icon.memory.meteocons.meteor-icons.mi.mingcute.mono-icons.mynaui.nimbus.nonicons.noto-v1.noto.nrk.octicon.oi.ooui.openmoji.osmic.oui.pajamas.pepicons-pencil.pepicons-pop.pepicons-print.pepicons.ph.picon.pinhead.pixel.pixelarticons.prime.proicons.ps.qlementine-icons.quill.radix-icons.raphael.ri.rivet-icons.roentgen.selfhst.si-glyph.si.sidekickicons.simple-icons.simple-line-icons.skill-icons.solar.stash.streamline-block.streamline-color.streamline-cyber-color.streamline-cyber.streamline-emojis.streamline-flex-color.streamline-flex.streamline-freehand-color.streamline-freehand.streamline-guidance.streamline-kameleon-color.streamline-logos.streamline-pixel.streamline-plump-color.streamline-plump.streamline-sharp-color.streamline-sharp.streamline-stickies-color.streamline-ultimate-color.streamline-ultimate.streamline.subway.svg-spinners.system-uicons.tabler.tdesign.teenyicons.temaki.token-branded.token.topcoat.twemoji.typcn.uil.uim.uis.uit.uiw.unjs.vaadin.vs.vscode-icons.websymbol.weui.whh.wi.wordpress.wpf.zmdi.zondicons`.split(`.`);function c(t){return n((n={})=>{let{scale:a=1,mode:c=`auto`,warn:l=!1,iconifyCollectionsNames:u,collections:m,extraProperties:h={},customizations:g={},autoInstall:_=!1,collectionsNodeResolvePath:v,layer:y=`icons`,unit:b,processor:x}=n,S=r(),C={addXmlNs:!0,scale:a,customCollections:m,autoInstall:_,cwd:v,warn:void 0,customizations:{...g,additionalProps:{...h},trimCustomSvg:!0,async iconCustomizer(e,t,n){await g.iconCustomizer?.(e,t,n),b&&(n.width||=`${a}${b}`,n.height||=`${a}${b}`)}}},w=new Set([...s,...u||[],...Object.keys(m||{})]),T,E=()=>{if(!T){let e=Promise.resolve().then(()=>t(n));T=e,e.catch(()=>{T===e&&(T=void 0)})}return T},D=async(e,t)=>{let n=f(e,w);if(n)return p(n,await E(),t?{...C,usedProps:t}:C)};return{name:`@teacss/preset-icons`,enforce:`pre`,options:n,layers:{[y]:-30},api:{encodeSvgForCss:o,parseIconWithLoader:d,resolveIcon:e=>D(e)},rules:[[e,async e=>{let[t,n,r=c]=e,a={},s=await D(n,a);if(!s){l&&!S.isESLint&&i(`failed to load icon "${t}"`);return}let u,d=`url("data:image/svg+xml;utf8,${o(s.svg)}")`;return r===`auto`&&(r=/currentcolor/i.test(s.svg)?`mask`:`bg`),u=r===`mask`?{"--tea-icon":d,display:`inline-block`,"-webkit-mask":`var(--tea-icon) no-repeat`,mask:`var(--tea-icon) no-repeat`,"-webkit-mask-size":`100% 100%`,"mask-size":`100% 100%`,"background-color":`currentColor`,"background-image":`none`,color:`inherit`,...a}:{display:`inline-block`,"-webkit-mask":`none`,mask:`none`,background:`${d} no-repeat`,"background-size":`100% 100%`,"background-color":`transparent`,...a},await x?.(u,{...s,icon:s.name,mode:r}),u},{layer:y}]]}})}function l(e){return(async(...t)=>{for(let n of e){if(!n)continue;let e=await n(...t);if(e)return e}})}function u(e,n,r=new Map){function i(i){if(!r.has(i)){let a=Promise.resolve().then(()=>e(`${n}@iconify-json/${i}/icons.json`)).then(e=>{let n=t(e);if(!n||n.prefix!==i)throw TypeError(`Invalid Iconify collection data for "${i}"`);return n});r.set(i,a),a.catch(()=>{r.get(i)===a&&r.delete(i)})}return r.get(i)}return async(e,t,n)=>{let r=await i(e);if(r)return await a(r,e,[t,t.replace(/([a-z])([A-Z])/g,`$1-$2`).toLowerCase(),t.replace(/([a-z])(\d+)/g,`$1-$2`)],n)}}async function d(e,t,n={},r=[]){let i=f(e,new Set([...s,...r,...Object.keys(n.customCollections||{})]));if(i)return p(i,t,n)}function f(e,t){let n=e.split(`-`);if(!(n.length<2||n.some(e=>e.length===0)))for(let e=n.length-1;e>=1;e--){let r=n.slice(0,e).join(`-`);if(t.has(r))return{collection:r,name:n.slice(e).join(`-`)}}}async function p(e,t,n){let r=await t(e.collection,e.name,n);if(r)return{...e,svg:r}}export{s as a,d as i,u as n,c as r,l as t};

package/dist/core-CmBaHpDm.d.ts

@@ -0,0 +1,129 @@
+import { CustomIconLoader, IconCustomizations, IconifyLoaderOptions, InlineCollection, UniversalIconLoader } from "@iconify/utils";
+import { Awaitable, CSSObject } from "@teacss/core";
+import { encodeSvgForCss } from "@iconify/utils/lib/svg/encode-svg-for-css";
+import { IconifyJSON } from "@iconify/types";
+//#region src/types.d.ts
+interface ParsedIcon {
+  collection: string;
+  name: string;
+  svg: string;
+}
+interface IconMeta extends ParsedIcon {
+  mode?: IconsOptions["mode"];
+  /**
+   * @deprecated renamed to `name`
+   */
+  icon: string;
+}
+interface IconsOptions {
+  /**
+   * Scale related to the current font size (1em).
+   *
+   * @default 1
+   */
+  scale?: number;
+  /**
+   * Mode of generated CSS icons.
+   *
+   * - `mask` - use background color and the `mask` property for monochrome icons
+   * - `bg` - use background image for the icons, colors are static
+   * - `auto` - smartly decide mode between `mask` and `bg` per icon based on its style
+   *
+   * @default 'auto'
+   * @see https://antfu.me/posts/icons-in-pure-css
+   */
+  mode?: "mask" | "bg" | "auto";
+  /**
+   * Extra CSS properties applied to the generated CSS
+   *
+   * @default {}
+   */
+  extraProperties?: Record<string, string>;
+  /**
+   * Emit warning when missing icons are matched
+   *
+   * @default false
+   */
+  warn?: boolean;
+  /**
+   * `@iconify-json` collections to use (will be also auto installed when missing and `autoInstall` enabled).
+   *
+   * This option should be used only when there are new `@iconify-json` collections not listed in the default icons preset collection names.
+   *
+   * Adding external collections will not work, you should use `FileSystemIconLoader` from
+   * `@iconify/utils/lib/loader/fs` or `createExternalPackageIconLoader` from
+   * `@iconify/utils/lib/loader/external-pkg` instead.
+   *
+   */
+  iconifyCollectionsNames?: string[];
+  /**
+   * In Node.js environment, the preset will search for the installed iconify dataset automatically.
+   * When using in the browser, this options is provided to provide dataset with custom loading mechanism.
+   */
+  collections?: Record<string, (() => Awaitable<IconifyJSON>) | undefined | CustomIconLoader | InlineCollection>;
+  /**
+   * Rule layer
+   *
+   * @default 'icons'
+   */
+  layer?: string;
+  /**
+   * Custom icon customizations.
+   */
+  customizations?: Omit<IconCustomizations, "additionalProps" | "trimCustomSvg">;
+  /**
+   * Auto install icon sources package when the usages is detected
+   *
+   * Only effective in Node.js environment.
+   *
+   * @default false
+   */
+  autoInstall?: boolean;
+  /**
+   * Path to resolve the iconify collections in Node.js environment.
+   *
+   * @default process.cwd()
+   */
+  collectionsNodeResolvePath?: string | string[];
+  /**
+   * Custom icon unit.
+   *
+   * @default `em`
+   */
+  unit?: string;
+  /**
+   * Load icons from CDN. Should starts with `https://` and ends with `/`
+   *
+   * Recommends:
+   * - https://esm.sh/
+   * - https://cdn.skypack.dev/
+   */
+  cdn?: string;
+  /**
+   * Custom fetch function used with `cdn` to return parsed Iconify collection data.
+   */
+  customFetch?: (url: string) => Promise<IconifyJSON>;
+  /**
+   * Processor for the CSS object before stringify
+   */
+  processor?: (cssObject: CSSObject, meta: Required<IconMeta>) => Awaitable<void>;
+}
+//#endregion
+//#region src/collections.d.ts
+declare const _default: string[];
+//#endregion
+//#region src/core.d.ts
+/**
+ * API for preset-icons
+ */
+interface IconsAPI {
+  encodeSvgForCss: typeof encodeSvgForCss;
+  parseIconWithLoader: typeof parseIconWithLoader;
+  resolveIcon: (name: string) => Promise<ParsedIcon | undefined>;
+}
+declare function createPresetIcons(lookupIconLoader: (options: IconsOptions) => Promise<UniversalIconLoader>): import("@teacss/core").PresetFactory<object, IconsOptions>;
+declare function combineLoaders(loaders: UniversalIconLoader[]): UniversalIconLoader;
+declare function createCDNFetchLoader(fetcher: (url: string) => Promise<IconifyJSON>, cdnBase: string, cacheMap?: Map<string, IconifyJSON | Promise<IconifyJSON>>): UniversalIconLoader;
+declare function parseIconWithLoader(body: string, loader: UniversalIconLoader, options?: IconifyLoaderOptions, safeCollectionsNames?: string[]): Promise<ParsedIcon | undefined>;
+//#endregion
+export { parseIconWithLoader as a, ParsedIcon as c, createPresetIcons as i, combineLoaders as n, _default as o, createCDNFetchLoader as r, IconsOptions as s, IconsAPI as t };

package/dist/core.d.ts

@@ -0,0 +1,2 @@
+import { a as parseIconWithLoader, c as ParsedIcon, i as createPresetIcons, n as combineLoaders, o as _default, r as createCDNFetchLoader, s as IconsOptions, t as IconsAPI } from "./core-CmBaHpDm.js";
+export { IconsAPI, type IconsOptions, type ParsedIcon, combineLoaders, createCDNFetchLoader, createPresetIcons, _default as icons, parseIconWithLoader };

package/dist/core.js

@@ -0,0 +1 @@
+import{a as e,i as t,n,r,t as i}from"./core-By2NcOr9.js";export{i as combineLoaders,n as createCDNFetchLoader,r as createPresetIcons,e as icons,t as parseIconWithLoader};

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { a as parseIconWithLoader, c as ParsedIcon, i as createPresetIcons, n as combineLoaders, o as _default, r as createCDNFetchLoader, s as IconsOptions, t as IconsAPI } from "./core-CmBaHpDm.js";
+//#region src/index.d.ts
+/**
+ * Use any icon with Pure CSS for TeaCSS.
+ *
+ * @example
+ *
+ * ```html
+ * <div class="icon:mdi-alarm"></div>
+ * <div class="icon:logos-vue font-size:3x"></div>
+ * <button class="icon:carbon-sun icon:carbon-moon@dark"></button>
+ * ```
+ *
+ */
+declare const presetIcons: import("@teacss/core").PresetFactory<object, IconsOptions>;
+//#endregion
+export { IconsAPI, type IconsOptions, type ParsedIcon, combineLoaders, createCDNFetchLoader, createPresetIcons, presetIcons as default, presetIcons, _default as icons, parseIconWithLoader };

package/dist/index.js

@@ -0,0 +1 @@
+import{a as e,i as t,n,r,t as i}from"./core-By2NcOr9.js";import{t as a}from"./cdn-BAAzT6MS.js";import{loadIcon as o}from"@iconify/utils";import{getEnvFlags as s}from"@teacss/core";const c=r(async e=>{let{cdn:t,customFetch:r}=e,c=[],u=!1,{isNode:d,isVSCode:f,isESLint:p}=s();if(d&&!f&&!p){let e=await l();e!==void 0&&(c.push(e),u=!0)}return u||c.push(o),t&&c.push(r?n(r,t):await a(t)),i(c)});async function l(){try{return await import(`@iconify/utils/lib/loader/node-loader`).then(e=>e?.loadNodeIcon)}catch{}}export{i as combineLoaders,n as createCDNFetchLoader,r as createPresetIcons,c as default,c as presetIcons,e as icons,t as parseIconWithLoader};

package/dist/merge.d.ts

@@ -0,0 +1,8 @@
+import { Merger, MergerPlugin } from "@teacss/classes";
+//#region src/merge.d.ts
+/** Merger metadata for the canonical `icon:<collection>-<name>` vocabulary. */
+declare const pluginIcon: MergerPlugin;
+/** Lazily initialized merger bound only to the canonical icon vocabulary. */
+declare const cn: Merger;
+//#endregion
+export { cn, pluginIcon };

package/dist/merge.js

@@ -0,0 +1 @@
+import{n as e}from"./syntax-DmIPw0tH.js";import{MERGE_OPAQUE as t,createMerger as n}from"@teacss/classes";const r={name:`@teacss/preset-icons/merge`,conflicts:{keywords:{},overlaps:{icon:`@teacss/preset-icons:icon`}},group(n){return n.prefix===`icon`?!n.keyword&&e(n.value)?null:t:null}};let i;const a=((...e)=>(i??=n({plugins:[r]}))(...e));export{a as cn,r as pluginIcon};

package/dist/syntax-DmIPw0tH.js

@@ -0,0 +1 @@
+const e=String.raw`[\w]+(?:-[\w]+)+`,t=RegExp(`^icon:(${e})(?:\\?(mask|bg|auto))?$`),n=RegExp(`^${e}(?:\\?(?:mask|bg|auto))?$`);function r(e){return e!=null&&n.test(e)}export{r as n,t};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@teacss/preset-icons",
+  "version": "0.3.0",
+  "description": "Pure-CSS Iconify icon utilities for TeaCSS — one class per icon, no runtime.",
+  "homepage": "https://css.teasim.com",
+  "funding": "https://github.com/sponsors/billgo",
+  "license": "MIT",
+  "author": "Billgo <hi@billgo.me>",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "browser": "./dist/browser.js",
+      "default": "./dist/index.js"
+    },
+    "./browser": "./dist/browser.js",
+    "./core": "./dist/core.js",
+    "./merge": "./dist/merge.js",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bunx rimraf dist && bunx tsdown --config tsdown.config.mts",
+    "dev": "tsdown --config-loader unrun --watch"
+  },
+  "dependencies": {
+    "@iconify/types": "^2.0.0",
+    "@iconify/utils": "^3.1.4",
+    "@teacss/classes": "0.3.0",
+    "@teacss/core": "0.3.0",
+    "ofetch": "^1.5.1"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}