@mal-icons/core 0.1.0

package/README.md

@@ -0,0 +1,103 @@
+# @mal-icons/core
+
+[![npm](https://img.shields.io/npm/v/@mal-icons/core.svg)](https://www.npmjs.com/package/@mal-icons/core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/mal-icons/mal-icons/blob/main/LICENSE)
+
+The framework-agnostic foundation of [**mal-icons**](https://github.com/mal-icons/mal-icons) —
+shared TypeScript types and theming utilities used by every framework adapter
+(React, Vue, Svelte, Preact, Solid, Angular, Astro, React Native, and the web
+renderer).
+
+You normally don't install this package directly — it ships as a dependency of
+each adapter. Install it only when you are **building your own adapter** or
+need the shared types and theming primitives in framework-neutral code.
+
+## Why it exists
+
+Every mal-icons adapter renders the **same SVG markup** from the **same data
+model**. `@mal-icons/core` is where that contract lives:
+
+- One serializable icon data model (`IconData`, `IconNode`, `NodeTuple`).
+- One prop surface (`IconBaseProps`) and theming contract (`IconContextValue`).
+- One override-resolution rule (`resolveIconAttrs`) so per-icon props always
+  beat context.
+- One set of differentiators: stroke `weight` presets and pure-CSS animations.
+
+There is **no runtime dependency** and **no framework code** — just types and a
+few tiny pure functions.
+
+## Installation
+
+```bash
+bun add @mal-icons/core
+# or
+npm install @mal-icons/core
+```
+
+## What's inside
+
+### Types
+
+| Export                 | Description                                                                                                                                                                                                |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `IconNode`             | Recursive `{ tag, attr, child }` build-time icon shape                                                                                                                                                     |
+| `NodeTuple`            | Compact `[tag, attr]` tuple used at render time                                                                                                                                                            |
+| `IconData`             | Minimal `{ viewBox, nodes, defaultAttr? }` render payload                                                                                                                                                  |
+| `IconDefinition`       | Fully-described, deduplicatable icon (used by the pipeline)                                                                                                                                                |
+| `IconBaseProps<St>`    | Props every generated icon component accepts                                                                                                                                                               |
+| `IconContextValue<St>` | Theming values supplied through a framework provider                                                                                                                                                       |
+| `IconsManifest`        | Top-level manifest describing all available icon sets                                                                                                                                                      |
+| `IconWeight`           | `"thin" \| "light" \| "regular" \| "bold"`                                                                                                                                                                 |
+| `IconAnimation`        | `"spin" \| "spin-reverse" \| "pulse" \| "beat" \| "bounce" \| "ping" \| "shake" \| "wiggle" \| "float" \| "heartbeat" \| "flip" \| "rotate" \| "zoom" \| "fade" \| "slide" \| "glow" \| "swing" \| "tada"` |
+
+### Utilities
+
+```ts
+import {
+  resolveIconAttrs,
+  WEIGHT_STROKE_WIDTH,
+  animationClass,
+  ICON_ANIMATIONS_CSS,
+} from "@mal-icons/core";
+
+// Merge per-icon props over context, following the override priority:
+//   props.color > context.color
+//   props.size  > context.size > "1em"
+const { size, color, className } = resolveIconAttrs(
+  { size: 24, color: "#3366ff" },
+  { size: 20 },
+);
+
+// Map a stroke weight preset to a concrete stroke-width.
+WEIGHT_STROKE_WIDTH.bold; // 3
+
+// Class name applied to the <svg> for a CSS animation.
+animationClass("spin"); // "mal-icons-animate-spin"
+
+// Inject once to enable the CSS animation presets (with a built-in
+// prefers-reduced-motion guard).
+document.head.insertAdjacentHTML(
+  "beforeend",
+  `<style>${ICON_ANIMATIONS_CSS}</style>`,
+);
+```
+
+## Building your own adapter
+
+A framework adapter only needs to:
+
+1. Read theming from `IconContextValue` via the framework's context/provider.
+2. Call `resolveIconAttrs(props, context)` to compute the final attributes.
+3. Render an `<svg viewBox={data.viewBox}>` and map `data.nodes` to elements.
+
+That's the entire contract — the generated icon modules supply the `IconData`.
+
+## Repository
+
+Source, issues, and contribution guidelines live in the monorepo:
+<https://github.com/mal-icons/mal-icons> · package directory
+[`packages/core`](https://github.com/mal-icons/mal-icons/tree/main/packages/core).
+
+## License
+
+[MIT](https://github.com/mal-icons/mal-icons/blob/main/LICENSE) © MALDevs

package/dist/index.cjs

@@ -0,0 +1,73 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// packages/core/src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  resolveIconAttrs: () => resolveIconAttrs,
+  animationClass: () => animationClass,
+  WEIGHT_STROKE_WIDTH: () => WEIGHT_STROKE_WIDTH,
+  ICON_ANIMATIONS_CSS: () => ICON_ANIMATIONS_CSS
+});
+module.exports = __toCommonJS(exports_src);
+var WEIGHT_STROKE_WIDTH = {
+  thin: 1,
+  light: 1.5,
+  regular: 2,
+  bold: 3
+};
+function animationClass(animation) {
+  return `mal-icon-animate-${animation}`;
+}
+var ICON_ANIMATIONS_CSS = `@keyframes mal-icon-spin{to{transform:rotate(360deg)}}
+@keyframes mal-icon-pulse{0%,100%{opacity:1}50%{opacity:.4}}
+@keyframes mal-icon-beat{0%,100%{transform:scale(1)}50%{transform:scale(1.15)}}
+@keyframes mal-icon-bounce{0%,100%{transform:translateY(0)}50%{transform:translateY(-15%)}}
+.mal-icon-animate-spin{animation:mal-icon-spin 1s linear infinite;will-change:transform}
+.mal-icon-animate-spin-reverse{animation:mal-icon-spin 1s linear infinite reverse;will-change:transform}
+.mal-icon-animate-pulse{animation:mal-icon-pulse 1.5s ease-in-out infinite}
+.mal-icon-animate-beat{animation:mal-icon-beat 1s ease-in-out infinite;will-change:transform}
+.mal-icon-animate-bounce{animation:mal-icon-bounce 1s ease infinite;will-change:transform}
+@media (prefers-reduced-motion:reduce){[class*=mal-icon-animate-]{animation:none}}
+`;
+function resolveIconAttrs(props, context) {
+  const size = props.size ?? context.size ?? "1em";
+  const color = props.color ?? context.color;
+  const className = [context.className, props.className].filter(Boolean).join(" ") || undefined;
+  return { size, color, className };
+}

package/dist/index.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Framework-agnostic icon data model.
+ *
+ * At build time we emit compile-time component code, but this is the
+ * intermediate, serializable model used by the pipeline and adapters.
+ */
+export interface IconNode {
+    /** Element tag, e.g. "path", "g", "circle". */
+    tag: string;
+    /** Element attributes, e.g. `{ d: "M0 0..." }`. */
+    attr: Record<string, string>;
+    /** Nested child nodes. */
+    child: IconNode[];
+}
+/**
+ * A compact `[tag, attributes]` tuple used by the runtime `createIcon`
+ * factory. Children are built once at module load, never per render.
+ */
+export type NodeTuple = [tag: string, attr: Record<string, string>];
+/**
+ * Minimal, serializable icon payload used by lazy/CDN and dynamic-by-name
+ * loaders. Mirrors what `createIcon` needs to render without bundling the
+ * whole set.
+ */
+export interface IconData {
+    /** SVG viewBox, e.g. "0 0 24 24". */
+    viewBox: string;
+    /** Shape children as compact tuples. */
+    nodes: NodeTuple[];
+    /** Optional root attributes (e.g. `fill: "none"`) for stroke-style sets. */
+    defaultAttr?: Record<string, string | number>;
+}
+/** A fully-described, deduplicatable icon definition. */
+export interface IconDefinition {
+    /** PascalCase component name, e.g. "FiActivity". */
+    name: string;
+    /** Set identifier, e.g. "fi" (Feather), "fa" (Font Awesome). */
+    set: string;
+    /** SVG viewBox, e.g. "0 0 24 24". */
+    viewBox: string;
+    /** Shape children of the icon. */
+    nodes: IconNode[];
+    /** Stable content hash, used for deduplication and determinism. */
+    contentHash: string;
+}
+/** A single icon set entry within the manifest. */
+export interface IconSetManifestEntry {
+    /** Set identifier, e.g. "fa". */
+    id: string;
+    /** Human-readable name, e.g. "Font Awesome 6". */
+    name: string;
+    /** SPDX (or free-form) license identifier of the source set. */
+    license: string;
+    /** Number of icons in the set. */
+    count: number;
+}
+/** Top-level manifest describing all available icon sets. */
+export interface IconsManifest {
+    sets: IconSetManifestEntry[];
+}
+/**
+ * Runtime props accepted by every generated icon component.
+ *
+ * `St` is the framework-specific inline-style type, kept generic so
+ * `core` stays framework-agnostic.
+ */
+export interface IconBaseProps<St = Record<string, unknown>> {
+    /** Width and height. Defaults to "1em". */
+    size?: string | number;
+    /** Overrides `currentColor`. */
+    color?: string;
+    /** Accessible label; renders a `<title>` element. */
+    title?: string;
+    /** Additional class name(s). */
+    className?: string;
+    /** Inline styles. */
+    style?: St;
+}
+/**
+ * Theming configuration provided through a framework context/provider.
+ * Per-icon props always override these context values.
+ */
+export interface IconContextValue<St = Record<string, unknown>> {
+    color?: string;
+    size?: string | number;
+    className?: string;
+    style?: St;
+    /** Extra attributes spread onto the root `<svg>`. */
+    attr?: Record<string, string>;
+}
+/** Resolved attributes returned by {@link resolveIconAttrs}. */
+export interface ResolvedIconAttrs {
+    size: string | number;
+    color: string | undefined;
+    className: string | undefined;
+}
+/** Stroke weight presets for stroke-based icon sets. */
+export type IconWeight = "thin" | "light" | "regular" | "bold";
+/** Maps a {@link IconWeight} to a concrete SVG `stroke-width`. */
+export declare const WEIGHT_STROKE_WIDTH: Record<IconWeight, number>;
+/** CSS-driven animation presets applied via the `animate` prop. */
+export type IconAnimation = "spin" | "spin-reverse" | "pulse" | "beat" | "bounce";
+/** Class name applied to the root `<svg>` for a given animation. */
+export declare function animationClass(animation: IconAnimation): string;
+/**
+ * CSS keyframes + classes backing {@link IconAnimation}. Consumers inject
+ * this once (e.g. a `<style>` tag); animations are pure CSS so they add no
+ * JS cost and only animate the icons that opt in (SRS §16.2).
+ */
+export declare const ICON_ANIMATIONS_CSS = "@keyframes mal-icons-spin{to{transform:rotate(360deg)}}\n@keyframes mal-icons-pulse{0%,100%{opacity:1}50%{opacity:.4}}\n@keyframes mal-icons-beat{0%,100%{transform:scale(1)}50%{transform:scale(1.15)}}\n@keyframes mal-icons-bounce{0%,100%{transform:translateY(0)}50%{transform:translateY(-15%)}}\n.mal-icons-animate-spin{animation:mal-icons-spin 1s linear infinite;will-change:transform}\n.mal-icons-animate-spin-reverse{animation:mal-icons-spin 1s linear infinite reverse;will-change:transform}\n.mal-icons-animate-pulse{animation:mal-icons-pulse 1.5s ease-in-out infinite}\n.mal-icons-animate-beat{animation:mal-icons-beat 1s ease-in-out infinite;will-change:transform}\n.mal-icons-animate-bounce{animation:mal-icons-bounce 1s ease infinite;will-change:transform}\n@media (prefers-reduced-motion:reduce){[class*=mal-icons-animate-]{animation:none}}\n";
+/**
+ * Resolve the final size/color/className given per-icon props and the
+ * surrounding context, following the SRS override priority:
+ *
+ * ```
+ * props.color  > context.color
+ * props.size   > context.size  > "1em"
+ * className = context.className + " " + props.className
+ * ```
+ */
+export declare function resolveIconAttrs(props: {
+    size?: string | number;
+    color?: string;
+    className?: string;
+}, context: {
+    size?: string | number;
+    color?: string;
+    className?: string;
+}): ResolvedIconAttrs;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,33 @@
+// packages/core/src/index.ts
+var WEIGHT_STROKE_WIDTH = {
+  thin: 1,
+  light: 1.5,
+  regular: 2,
+  bold: 3
+};
+function animationClass(animation) {
+  return `mal-icon-animate-${animation}`;
+}
+var ICON_ANIMATIONS_CSS = `@keyframes mal-icon-spin{to{transform:rotate(360deg)}}
+@keyframes mal-icon-pulse{0%,100%{opacity:1}50%{opacity:.4}}
+@keyframes mal-icon-beat{0%,100%{transform:scale(1)}50%{transform:scale(1.15)}}
+@keyframes mal-icon-bounce{0%,100%{transform:translateY(0)}50%{transform:translateY(-15%)}}
+.mal-icon-animate-spin{animation:mal-icon-spin 1s linear infinite;will-change:transform}
+.mal-icon-animate-spin-reverse{animation:mal-icon-spin 1s linear infinite reverse;will-change:transform}
+.mal-icon-animate-pulse{animation:mal-icon-pulse 1.5s ease-in-out infinite}
+.mal-icon-animate-beat{animation:mal-icon-beat 1s ease-in-out infinite;will-change:transform}
+.mal-icon-animate-bounce{animation:mal-icon-bounce 1s ease infinite;will-change:transform}
+@media (prefers-reduced-motion:reduce){[class*=mal-icon-animate-]{animation:none}}
+`;
+function resolveIconAttrs(props, context) {
+  const size = props.size ?? context.size ?? "1em";
+  const color = props.color ?? context.color;
+  const className = [context.className, props.className].filter(Boolean).join(" ") || undefined;
+  return { size, color, className };
+}
+export {
+  resolveIconAttrs,
+  animationClass,
+  WEIGHT_STROKE_WIDTH,
+  ICON_ANIMATIONS_CSS
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@mal-icons/core",
+  "version": "0.1.0",
+  "description": "Framework-agnostic types and theming utilities for mal-icons.",
+  "type": "module",
+  "license": "MIT",
+  "author": "MALDevs",
+  "homepage": "https://github.com/mal-icons/mal-icons#readme",
+  "bugs": {
+    "url": "https://github.com/mal-icons/mal-icons/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mal-icons/mal-icons.git",
+    "directory": "packages/core"
+  },
+  "keywords": ["icons", "svg", "typescript", "theming", "mal-icons"],
+  "sideEffects": false,
+  "files": ["dist", "!dist/.tsbuildinfo"],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}