@nine-thirty-five/material-symbols-react 2.1.5 → 2.2.1

package/README.md

@@ -2,15 +2,14 @@
 
 Use [Google's Material Symbols](https://fonts.google.com/icons?icon.set=Material+Symbols) in React — **every style, weight and fill**, fully tree-shakeable, zero runtime dependencies.
 
-<div align="center">
+Live example: [nine-thirty-five.github.io/material-symbols-react](https://nine-thirty-five.github.io/material-symbols-react)
+
 
 [![NPM version][npm-image]][npm-url]
 [![Downloads][download-image]][npm-downloads]
 ![npm-typescript]
 [![GitHub License](https://img.shields.io/badge/license-Apache--2.0-green)](./LICENSE)
 
-</div>
-
 - [Installation](#installation)
 - [Usage](#usage)
   - [Importing](#importing)
@@ -96,6 +95,19 @@ Every icon accepts all SVG props (`SVGProps<SVGSVGElement>`), plus a convenience
 - **`size`** — `number | string`. Sets both `width` and `height`. Defaults to `"1em"`, so icons
   scale with the surrounding `font-size`. Pass `width`/`height` explicitly to override.
 - **Color** — icons render with `fill="currentColor"`, so they inherit `color` from CSS.
+- **`title`** — accessible label, rendered as an SVG `<title>` with `role="img"`.
+
+### Accessibility
+
+Icons are **decorative by default**: they render with `aria-hidden="true"` so screen readers skip
+them. To make an icon meaningful, give it a label — via `title`, `aria-label`, or
+`aria-labelledby` — and it switches to `role="img"` with the label as its accessible name:
+
+```tsx
+<Delete />                    {/* decorative: aria-hidden="true" */}
+<Delete title="Delete item" /> {/* semantic: role="img" + <title> */}
+<Delete aria-label="Delete item" />
+```
 
 ## Tree-shaking & bundle size
 
@@ -146,11 +158,29 @@ The catalog is also importable directly:
 import manifest from '@nine-thirty-five/material-symbols-react/manifest.json' with { type: 'json' };
 ```
 
+### Search from the command line
+
+The package ships a tiny dependency-free CLI over the same catalog:
+
+```bash
+npx @nine-thirty-five/material-symbols-react find trash
+```
+
+```text
+Delete            delete  [UI actions]
+DeleteForever     delete_forever  [UI actions]
+…
+
+import { Delete } from '@nine-thirty-five/material-symbols-react/outlined';
+```
+
+Options: `--limit/-n <N>` (default 10), `--json` for machine-readable output.
+
 ## ESM only
 
-This package ships **ES Modules only**. It works in all modern bundlers and ESM Node. If you need
-to consume it from a CommonJS module under `node16`/`nodenext` resolution, use a dynamic
-`import()`.
+This package ships **ES Modules only**. It works in all modern bundlers and ESM Node. On
+Node ≥ 22, CommonJS code can `require()` it directly thanks to `require(esm)`; on older Node or
+under `node16`/`nodenext` TypeScript resolution from CJS, use a dynamic `import()`.
 
 ## Migrating from v1
 

package/bin/find.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import { searchIcons } from './search.js';
+
+const USAGE = `Search the Material Symbols catalog shipped with this package.
+
+Usage:
+  npx @nine-thirty-five/material-symbols-react find <query…> [options]
+
+Options:
+  --limit, -n <N>   Maximum results to print (default 10)
+  --json            Print raw JSON (name, component, categories, tags)
+  --help, -h        Show this help
+
+Examples:
+  npx @nine-thirty-five/material-symbols-react find trash
+  npx @nine-thirty-five/material-symbols-react find arrow back -n 5
+`;
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (argv[0] === 'find' || argv[0] === 'search') argv.shift();
+
+  let limit = 10;
+  let json = false;
+  const query = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') {
+      console.log(USAGE);
+      return;
+    } else if (a === '--json') {
+      json = true;
+    } else if (a === '--limit' || a === '-n') {
+      limit = parseInt(argv[++i], 10) || 10;
+    } else {
+      query.push(a);
+    }
+  }
+  if (query.length === 0) {
+    console.log(USAGE);
+    process.exitCode = 1;
+    return;
+  }
+
+  // bin/ and dist/ are siblings both in the published package and in the repo.
+  const manifestUrl = new URL('../dist/manifest.json', import.meta.url);
+  if (!fs.existsSync(manifestUrl)) {
+    console.error(
+      'dist/manifest.json not found — in a repo checkout, run `npm run generate:sample` first.'
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestUrl, 'utf8'));
+  const results = searchIcons(manifest.icons, query, limit);
+
+  if (json) {
+    console.log(JSON.stringify(results, null, 2));
+    return;
+  }
+  if (results.length === 0) {
+    console.log(`No icons match "${query.join(' ')}".`);
+    return;
+  }
+
+  const width = Math.max(...results.map((r) => r.component.length));
+  for (const r of results) {
+    const cats = r.categories?.length ? `  [${r.categories.join(', ')}]` : '';
+    console.log(`${r.component.padEnd(width)}  ${r.name}${cats}`);
+  }
+  console.log(
+    `\nimport { ${results[0].component} } from '${manifest.package}/outlined';`
+  );
+  console.log(`Pattern: ${manifest.importPattern}`);
+}
+
+main();

package/bin/search.d.ts

@@ -0,0 +1,18 @@
+export interface ManifestIcon {
+  /** Material Symbols name (snake_case). */
+  name: string;
+  /** Exported component identifier (PascalCase). */
+  component: string;
+  categories: string[];
+  tags: string[];
+}
+
+/**
+ * Rank `icons` against query terms. Every term must match somewhere
+ * (name, component, tags or categories) for an icon to qualify.
+ */
+export declare function searchIcons(
+  icons: ManifestIcon[],
+  query: string[],
+  limit?: number
+): ManifestIcon[];

package/bin/search.js

@@ -0,0 +1,47 @@
+/**
+ * Search over the manifest.json icon catalog that ships with the package.
+ * Pure and dependency-free so it can be unit-tested without a generated dist.
+ */
+
+/** Score one icon against a single lower-cased term. 0 = no match. */
+function scoreTerm(icon, term) {
+  const name = icon.name.toLowerCase();
+  const component = icon.component.toLowerCase();
+  if (name === term || component === term) return 100;
+  if (name.split('_').includes(term)) return 50;
+  if (name.includes(term) || component.includes(term)) return 30;
+  const tags = icon.tags ?? [];
+  if (tags.some((t) => t.toLowerCase() === term)) return 25;
+  if (tags.some((t) => t.toLowerCase().includes(term))) return 10;
+  const categories = icon.categories ?? [];
+  if (categories.some((c) => c.toLowerCase().includes(term))) return 5;
+  return 0;
+}
+
+/**
+ * Rank icons against query terms. Every term must match somewhere
+ * (name, component, tags or categories) for an icon to qualify.
+ */
+export function searchIcons(icons, query, limit = 10) {
+  const terms = query.map((t) => t.toLowerCase().trim()).filter(Boolean);
+  if (terms.length === 0) return [];
+
+  const scored = [];
+  for (const icon of icons) {
+    let total = 0;
+    for (const term of terms) {
+      const s = scoreTerm(icon, term);
+      if (s === 0) {
+        total = 0;
+        break;
+      }
+      total += s;
+    }
+    if (total > 0) scored.push({ icon, score: total });
+  }
+
+  scored.sort(
+    (a, b) => b.score - a.score || a.icon.name.localeCompare(b.icon.name)
+  );
+  return scored.slice(0, limit).map((s) => s.icon);
+}

package/dist/_base.d.ts

@@ -3,6 +3,12 @@ import type { ForwardRefExoticComponent, RefAttributes, SVGProps } from 'react';
 export interface IconProps extends Omit<SVGProps<SVGSVGElement>, 'ref'> {
   /** Sets both width and height. Defaults to "1em" so icons scale with font-size. */
   size?: number | string;
+  /**
+   * Accessible label, rendered as an SVG `<title>` with `role="img"`.
+   * Without it (or `aria-label`/`aria-labelledby`) the icon is decorative
+   * and gets `aria-hidden="true"`.
+   */
+  title?: string;
 }
 
 export type Icon = ForwardRefExoticComponent<

package/dist/_base.js

@@ -9,11 +9,20 @@ import { createElement, forwardRef } from 'react';
  * Wrapped in `forwardRef` so `<Icon ref={…} />` reaches the underlying `<svg>`
  * in both React 18 and 19.
  *
+ * Accessibility: icons are decorative by default (`aria-hidden="true"`).
+ * Passing `title`, `aria-label` or `aria-labelledby` makes the icon
+ * semantic instead: it gets `role="img"`, and `title` renders an SVG
+ * `<title>` as the accessible name.
+ *
  * @param {string} d - SVG path data.
  * @returns {import('./base').Icon}
  */
 const base = (d) =>
-  forwardRef(function Icon({ size = '1em', ...props }, ref) {
+  forwardRef(function Icon({ size = '1em', title, ...props }, ref) {
+    const labelled =
+      title != null ||
+      props['aria-label'] != null ||
+      props['aria-labelledby'] != null;
     return createElement(
       'svg',
       {
@@ -22,9 +31,12 @@ const base = (d) =>
         width: size,
         height: size,
         fill: 'currentColor',
+        'aria-hidden': labelled ? undefined : true,
+        role: labelled ? 'img' : undefined,
         ...props,
         ref,
       },
+      title ? createElement('title', null, title) : null,
       createElement('path', { d })
     );
   });