@menapo/icons 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 menapo
+
+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

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# @menapo/icons
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Icons as one typed call: `icon("lucide:check")` returns an element's
+attributes, and the Vite plugin compiles it to a literal and adds that
+icon's CSS, a mask in `currentColor` or a coloured background, to the module
+that names it. Zero runtime JavaScript, zero config, the same call in React,
+Preact, Vue, Svelte, Solid, Astro, plain code and markup templates.
+
+**Status: built, private until 1.0.** `icon()` with `label` and `class`, the
+plugin (sets detected from `@iconify-json/*`, local SVG folders, per-module
+CSS, `icons.d.ts`, errors with the closest names, dev updates) and
+`resolveIcon`/`iconName` for og are implemented and tested;
+`examples/icons-react` checks React, Vue and plain code in Chromium. The
+release waits on the owner's review.
+
+```ts
+// vite.config.ts
+import { icons } from "@menapo/icons/vite";
+
+export default defineConfig({ plugins: [icons()] });
+```
+
+```tsx
+import { icon } from "@menapo/icons";
+
+<span {...icon("lucide:check")} />;
+<button>
+  <span {...icon("lucide:x", { label: t("Close") })} />
+</button>;
+```
+
+- [Guide](./docs/guide/README.md): setup, labels, colour and size, runtime
+  choices, your own SVGs, every framework, and the reference.
+- [Plan](./docs/PLAN.md): the design, its decisions and measurements.
+- Benchmark: `vp run --filter @menapo/icons bench` (CSS bytes against
+  Iconify's own generator and inline SVG, parse and compile time).

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+//#region src/index.d.ts
+/**
+ * `@menapo/icons` (PLAN §0): `icon("lucide:x")` and its types. The plugin
+ * (`@menapo/icons/vite`) replaces every call with a literal object and
+ * imports the icon's CSS, so compiled code never calls the function below
+ * and no JavaScript of this package reaches the browser (D2).
+ */
+/**
+ * Filled by the generated `icons.d.ts` (D10): the installed names and the
+ * project's framework, the way vicss's `vicss.d.ts` registers its own.
+ */
+export interface Register {}
+/** Every icon the project can name: `"lucide:check" | … | "brand:logo"`. */
+export type IconName = Register extends {
+  names: infer N extends string;
+} ? N : `${string}:${string}`;
+/** The framework the generated types registered: React when none is. */
+type RegisteredFramework = Register extends {
+  framework: infer F extends string;
+} ? F : "react";
+/** React takes `className`; every other framework and kit's markup take `class` (D3). */
+type ClassAttribute = RegisteredFramework extends "react" ? "className" : "class";
+export interface IconOptions {
+  /**
+   * The icon carries meaning on its own: it gets `role="img"` and this
+   * `aria-label` instead of `aria-hidden`. Translate it: `t("Close")`.
+   */
+  readonly label?: string;
+  /** More classes, appended to the icon's: `"size-5 text-red-700"`, `sx(style).className`. */
+  readonly class?: string;
+}
+/** A decorative icon's attributes: hidden from assistive technology. */
+export type DecorativeIcon = { readonly [K in ClassAttribute]: string; } & {
+  readonly "aria-hidden": "true";
+};
+/** A labelled icon's attributes: an image with an accessible name. */
+export type LabelledIcon = { readonly [K in ClassAttribute]: string; } & {
+  readonly role: "img";
+  readonly "aria-label": string;
+};
+/**
+ * The attributes of an icon element: spread them on an empty element,
+ * `<span {...icon("lucide:check")} />`. The name is a string literal, so
+ * the plugin can compile it; a name chosen at runtime picks from an object
+ * of compiled calls.
+ */
+export declare function icon(name: IconName, options: IconOptions & {
+  readonly label: string;
+}): LabelledIcon;
+export declare function icon(name: IconName, options?: IconOptions): DecorativeIcon;
+//#endregion
+export {};

package/dist/index.js

@@ -0,0 +1,6 @@
+//#region src/index.ts
+function icon(name) {
+	throw new Error(`@menapo/icons: icon(${JSON.stringify(name)}) ran uncompiled. Add icons() from "@menapo/icons/vite" to the Vite config's plugins, and write the name as a string literal.`);
+}
+//#endregion
+export { icon };

package/dist/vite.d.ts

@@ -0,0 +1,69 @@
+import { Plugin } from "vite";
+//#region src/vite/svg.d.ts
+/**
+ * The SVG work both kinds of source share (D5, D13): cleaning a local file,
+ * reading its size, and deciding whether it is monochrome. Plain strings
+ * in and out, so it is unit-tested without files.
+ */
+/** One icon, ready for CSS or for inlining. */
+interface Svg {
+  /** The inner markup, with black painted in `currentColor` for a monochrome icon. */
+  readonly body: string;
+  readonly width: number;
+  readonly height: number;
+  /** Painted in `currentColor` (a mask), or keeping its own colours (a background). */
+  readonly mono: boolean;
+}
+//#endregion
+//#region src/vite/resolve.d.ts
+/** A resolved icon, with the file it came from (watched in dev). */
+interface ResolvedIcon extends Svg {
+  readonly name: string;
+  readonly file: string;
+}
+interface IconSourceOptions {
+  /** The project root: its `package.json` lists the sets. */
+  readonly root: string;
+  /** Local sets: a prefix mapped to a directory, relative to the root. */
+  readonly folders?: Readonly<Record<string, string>> | undefined;
+}
+//#endregion
+//#region src/vite/index.d.ts
+export interface IconsOptions {
+  /**
+   * The app's own SVGs: a set name mapped to a directory, relative to the
+   * root. `{ brand: "./src/icons" }` makes `src/icons/logo.svg` the icon
+   * `brand:logo`, and `arrows/left.svg` the icon `brand:arrows-left`.
+   * Installed `@iconify-json/*` sets need no option.
+   */
+  readonly folders?: Readonly<Record<string, string>>;
+}
+/** `plugins: [icons()]` in a Vite config. */
+export declare function icons(options?: IconsOptions): Plugin;
+/** The plugin's `api`: a renderer under it resolves the folders it was given. */
+export interface IconsApi {
+  readonly folders: IconsOptions["folders"];
+}
+/** An icon for a renderer that inlines SVG: og (D11), email later. */
+export interface InlineIcon extends ResolvedIcon {
+  /** The whole `<svg>` element; a monochrome icon paints in `currentColor`. */
+  readonly svg: string;
+}
+/**
+ * `lucide:check` to its SVG, from the sets and folders of the project at
+ * `root`, as the plugin resolves it. Throws a message naming the fix for an
+ * unknown name. Build side only: og calls it while it renders.
+ */
+export declare function resolveIcon(name: string, options: IconSourceOptions): InlineIcon;
+/**
+ * The name an `icon()` result stands for, read back from its classes:
+ * `iconName({ class: "mi mi-lucide--x" })` is `"lucide:x"`. A spread in a
+ * markup template is just attributes; this is how a renderer knows it is
+ * an icon. Takes `class` or `className` (D3).
+ */
+export declare function iconName(attributes: {
+  readonly class?: unknown;
+  readonly className?: unknown;
+}): string | undefined;
+//#endregion
+export type { ResolvedIcon };