@driftime/sanity-plugin-icon 0.1.0 → 0.3.0

package/README.md

@@ -1,38 +1,42 @@
 <div align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-icon/HEAD/.github/assets/icon-dark.svg" />
-    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-icon/HEAD/.github/assets/icon-light.svg" />
-    <img src="https://raw.githubusercontent.com/driftime/sanity-plugin-icon/HEAD/.github/assets/icon-light.svg" alt="Icon plugin logo" width="48" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugins/HEAD/packages/icon/assets/icon-dark.svg" />
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugins/HEAD/packages/icon/assets/icon-light.svg" />
+    <img src="https://raw.githubusercontent.com/driftime/sanity-plugins/HEAD/packages/icon/assets/icon-light.svg" alt="Icon plugin logo" width="48" />
   </picture>
   <h1>Icon</h1>
   <p><strong>A Sanity Studio plugin by Driftime®</strong></p>
-  <p>Lucide icons for Sanity Studio, stored as drawings and rendered without the library.</p>
+  <p>Lucide icons for Sanity Studio, stored as SVG and rendered without the library.</p>
+  <p>
+    <a href="https://www.npmjs.com/package/@driftime/sanity-plugin-icon"><img src="https://img.shields.io/npm/v/@driftime/sanity-plugin-icon?style=flat-square&labelColor=1a1a1a&color=666666" alt="npm version" /></a>
+    <a href="https://github.com/driftime/sanity-plugins/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@driftime/sanity-plugin-icon?style=flat-square&labelColor=1a1a1a&color=666666" alt="License: MIT" /></a>
+  </p>
 </div>
 
 <br />
 
 ## Overview
 
-Icon adds a field type to Sanity Studio that opens the whole Lucide library as a searchable grid. Authors find an icon by its name or by what it depicts, and the drawing itself is stored on the document alongside the name it was chosen by.
+Icons are part of a site's visual language, chosen with the same care as its typography and its colors, and Icon makes them part of its content too. The whole [Lucide](https://lucide.dev) library sits behind a field, searchable by name or by what an icon depicts, so the icon beside a heading, a feature, or a link is chosen where the heading is written.
 
-Rendering costs one component and **under 2 kB gzipped**, with no icon library in your application. That works because the document holds the drawing rather than a reference to it, so nothing needs resolving by name at runtime.
+When an icon is chosen, its drawing is stored on the document alongside its name. The site renders that drawing with one component and no icon library, so nothing is looked up at runtime, and an icon keeps rendering through every Lucide release, whatever that release renames or removes.
 
 <br />
 
 <figure>
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-icon/HEAD/.github/assets/icon-selector-dark.png" />
-    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-icon/HEAD/.github/assets/icon-selector-light.png" />
-    <img src="https://raw.githubusercontent.com/driftime/sanity-plugin-icon/HEAD/.github/assets/icon-selector-light.png" alt="The icon selector open in Sanity Studio, showing a search field above a scrolling grid of the complete Lucide library alongside a count of every icon it offers" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugins/HEAD/packages/icon/assets/icon-selector-dark.png" />
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugins/HEAD/packages/icon/assets/icon-selector-light.png" />
+    <img src="https://raw.githubusercontent.com/driftime/sanity-plugins/HEAD/packages/icon/assets/icon-selector-light.png" alt="The icon picker open in Sanity Studio, showing a search field above a scrolling grid of every Lucide icon" />
   </picture>
-  <p align="center"><sub><em>Every Lucide icon, searchable from inside the Studio.</em></sub></p>
+  <p align="center"><sub><em>The icon picker, with the whole library in a searchable grid.</em></sub></p>
 </figure>
 
 <br />
 
 ## Installation
 
-Icon is built for Sanity Studio 6 and React 19, and declares both as peer dependencies, so your Studio must already be on those versions. You'll need Node 22.12 or later.
+Icon is built for Sanity Studio 6.10 and React 19 and declares both as peer dependencies, so the Studio needs to be on those versions already. Node 22.12 or later is required.
 
 ```bash
 bun add -E @driftime/sanity-plugin-icon
@@ -40,101 +44,178 @@ bun add -E @driftime/sanity-plugin-icon
 
 <br />
 
-## Basic Setup
+## Studio
 
-Add the plugin to your Sanity configuration. It takes no options.
+In the Studio, the plugin registers an `icon` type and takes the icons every field offers.
+
+<br />
+
+### Registering the Plugin
+
+Nothing is required, and a plugin registered on its own offers every icon in the installed Lucide release.
 
 ```typescript
 import { defineConfig } from "sanity";
 import { iconPlugin } from "@driftime/sanity-plugin-icon";
-// ...
 
 export default defineConfig({
   // ...
-  plugins: [iconPlugin()],
+  plugins: [
+    // ...
+    iconPlugin(),
+  ],
 });
 ```
 
-That registers an `icon` object type, available alongside Sanity's own. Use it on any document or object.
+| Option  | Type               | Default | Purpose                                                                                             |
+| ------- | ------------------ | ------- | --------------------------------------------------------------------------------------------------- |
+| `icons` | `SanityIconName[]` | all     | Icons every field offers, in the order listed. See [Restricting the Icons](#restricting-the-icons). |
+
+<br />
+
+### Adding an Icon Field
+
+A field of type `icon` is defined like any other.
 
 ```typescript
 defineField({
   name: "icon",
   type: "icon",
-  description: "Shown beside the heading.",
+  description: "Icon shown beside the heading.",
 });
 ```
 
-The type is registered as `icon` and the name is not configurable, so a Studio that already defines its own `icon` type will need to rename that one.
+| Option  | Type               | Default           | Purpose                                                                       |
+| ------- | ------------------ | ----------------- | ----------------------------------------------------------------------------- |
+| `icons` | `SanityIconName[]` | the plugin's list | Icons this field offers. See [Restricting the Icons](#restricting-the-icons). |
+
+The type name is always `icon`, so a Studio that already has a type by that name needs to rename it before installing.
 
 <br />
 
-## Picking an Icon
+### Restricting the Icons
+
+A field offers the whole library unless restricted, and most sites want a smaller set. Pass the icons the site uses to the plugin, and every field offers those, in the order they are listed.
+
+```typescript
+iconPlugin({
+  icons: ["sun", "wind", "droplets", "leaf", "sprout", "mountain", "tent", "compass"],
+});
+```
+
+A single field sometimes needs a list of its own, for example a contact card whose icon should only ever be a mail, phone, or globe symbol. Pass `icons` in the field's `options`.
+
+```typescript
+defineField({
+  name: "icon",
+  type: "icon",
+  description: "Icon shown beside the contact method.",
+  options: { icons: ["mail", "phone", "globe"] },
+});
+```
+
+A field's list **replaces** the plugin's list, so a field can offer any icon regardless of the plugin's, and a name the installed Lucide release does not have is skipped. Restricting a field later is safe, because a stored icon carries its own drawing and still renders when the picker no longer offers it.
+
+Names are typed against the Lucide release installed in the project, so they complete as they are typed. A list shared between the plugin and a field, or between several fields, is typed with `SanityIconName`.
+
+```typescript
+import type { SanityIconName } from "@driftime/sanity-plugin-icon";
 
-- Search matches an icon's name and the terms it is tagged with, so "next" finds `arrow-right`.
-- The complete Lucide set is offered, and the count reflects whatever the current release holds.
-- The last eight icons chosen are remembered, per browser rather than per dataset.
+export const contactIcons: SanityIconName[] = ["mail", "phone", "globe"];
+```
 
 <br />
 
 <figure>
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-icon/HEAD/.github/assets/icon-search-dark.png" />
-    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugin-icon/HEAD/.github/assets/icon-search-light.png" />
-    <img src="https://raw.githubusercontent.com/driftime/sanity-plugin-icon/HEAD/.github/assets/icon-search-light.png" alt="The icon selector filtered by the term next, showing thirteen arrow and forward icons matched on what they depict rather than on their names" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugins/HEAD/packages/icon/assets/icon-search-dark.png" />
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/driftime/sanity-plugins/HEAD/packages/icon/assets/icon-search-light.png" />
+    <img src="https://raw.githubusercontent.com/driftime/sanity-plugins/HEAD/packages/icon/assets/icon-search-light.png" alt="The icon picker filtered by the search term next, showing every arrow and forward icon in the library" />
   </picture>
-  <p align="center"><sub><em>Searching matches what an icon depicts, so “next” finds every arrow.</em></sub></p>
+  <p align="center"><sub><em>Search matches an icon's name and the terms Lucide tags it with, so "next" finds every arrow.</em></sub></p>
 </figure>
 
 <br />
 
-## Rendering Icons
+### Document Previews
 
-`Icon` is exported from a separate import path that holds no Studio code, so it can be used anywhere outside the Studio, in server and client components alike. It needs no icon library of its own.
+A document's preview shows the icon its type was given in the schema, which is the same for every document of that type. `createIconPreview` shows the icon the author chose instead. Pass it the stored value in `prepare`.
 
-```tsx
-import { Icon } from "@driftime/sanity-plugin-icon/render";
+```typescript
+import { createIconPreview } from "@driftime/sanity-plugin-icon";
 
-<Icon value={home.icon} className="size-8" />;
+defineType({
+  // ...
+  preview: {
+    select: { title: "title", icon: "icon" },
+    prepare({ title, icon }) {
+      return { title, media: createIconPreview(icon) };
+    },
+  },
+});
 ```
 
-It takes the stored field value directly and renders nothing when that value is absent or unreadable. Props extend `ComponentProps<"svg">`, so `className`, `style`, `aria-label` and the rest pass through to the element.
+When nothing readable is stored, it returns `undefined` and the preview falls back to the type's own icon.
+
+<br />
 
-Type the field with `SanityIcon`, available from either import path.
+### Keeping the Library Current
 
-```typescript
-import type { SanityIcon } from "@driftime/sanity-plugin-icon";
+The plugin depends on Lucide with a caret range, so a newer release installs without a plugin release. The project's lockfile pins whichever release was installed, and there are two ways to move it forward. Removing and re-adding the plugin resolves the range again.
 
-export interface SanityHome {
-  title: string;
-  icon?: SanityIcon;
-}
+```bash
+bun remove @driftime/sanity-plugin-icon
+bun add -E @driftime/sanity-plugin-icon
 ```
 
+Adding `lucide-static` to the project's own dependencies puts the release under the project's control, and the plugin resolves to that copy from then on.
+
 <br />
 
-## Document Previews
+## Site
 
-A document's preview shows the icon its _type_ defines, which is the same glyph for every document of that type. `createIconPreview` builds preview media from the icon an author chose instead.
+On the site, one component draws a stored icon, and it is imported from `@driftime/sanity-plugin-icon/render`. That path carries no Studio code, so it is safe in server components and anywhere else on the site.
 
-```typescript
-import { createIconPreview } from "@driftime/sanity-plugin-icon";
+<br />
 
-preview: {
-  select: { title: "title", icon: "icon" },
-  prepare({ title, icon }) {
-    return { title, media: createIconPreview(icon) };
-  },
-},
+### Rendering Icons
+
+`Icon` draws the shapes held in the stored value, so no icon library is installed on the site. The markup is an `svg` element, and the component renders nothing when the value is missing or unreadable.
+
+```tsx
+import { Icon } from "@driftime/sanity-plugin-icon/render";
+import type { SanityIcon } from "@driftime/sanity-plugin-icon/render";
+
+interface FeatureProps {
+  icon: SanityIcon | undefined;
+  title: string;
+}
+
+export function Feature({ icon, title }: FeatureProps) {
+  return (
+    <article>
+      <Icon value={icon} className="size-8" />
+      <h3>{title}</h3>
+    </article>
+  );
+}
 ```
 
-It returns `undefined` when there is nothing to draw, so the preview falls back to Sanity's own placeholder.
+| Prop    | Type                      | Purpose                                                |
+| ------- | ------------------------- | ------------------------------------------------------ |
+| `value` | `SanityIcon \| undefined` | The stored icon. Required, though it may hold nothing. |
+
+Every other prop is an `svg` element's and is spread onto the root element after the plugin's own attributes, so `className`, `style`, and `strokeWidth` all apply. The icon is drawn on Lucide's frame, 24 by 24 with a stroke of 2, and `aria-hidden`, so assistive technology treats it as decoration beside its text. An icon that carries meaning on its own takes `aria-hidden={false}` and an `aria-label`.
+
+```tsx
+<Icon value={link.icon} aria-hidden={false} aria-label="Opens in a new tab" />
+```
 
 <br />
 
-## Querying
+### Querying
 
-A stored icon needs no special handling in a query. It comes down as a plain object alongside the rest of the document, with nothing to dereference or expand.
+An icon needs nothing special in a query. It comes back as a plain object with the rest of the document.
 
 ```groq
 *[_type == "home"][0] { title, icon }
@@ -142,47 +223,74 @@ A stored icon needs no special handling in a query. It comes down as a plain obj
 
 <br />
 
-## What Gets Stored
+## Reference
+
+The rest of this document covers the shape of a stored icon and everything the package exports.
+
+<br />
+
+### Stored Icons
+
+`SanityIcon` is the type of a stored icon.
+
+```typescript
+import type { SanityIcon } from "@driftime/sanity-plugin-icon/render";
+
+export interface SanityFeature {
+  icon?: SanityIcon;
+}
+```
 
 ```json
 {
   "_type": "icon",
   "name": "house",
-  "node": "[[\"path\",{\"d\":\"M15 21v-8a1 1 0 0 0-1-1h-4a1 1 0 0 0-1 1v8\"}], …]"
+  "node": "[[\"path\",{\"d\":\"M15 21v-8a1 1 0 0 0-1-1h-4a1 1 0 0 0-1 1v8\"}],[\"path\",{\"d\":\"M3 10a2 2 0 0 1 .709-1.528l7-6a2 2 0 0 1 2.582 0l7 6A2 2 0 0 1 21 10v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z\"}]]"
 }
 ```
 
-The `name` records which icon was chosen, and the `node` holds the shapes it is drawn from. Both are written when the icon is picked, which is what lets it render without an icon library.
+| Field   | Type     | Purpose                                                                               |
+| ------- | -------- | ------------------------------------------------------------------------------------- |
+| `_type` | `string` | Always `icon`.                                                                        |
+| `name`  | `string` | The icon's name in the Lucide release it was chosen from.                             |
+| `node`  | `string` | The shapes inside the icon's `svg` element, as JSON. Written when the icon is chosen. |
+
+Both fields are written together, which is what lets an icon render without a library. A stored icon with a name but no drawing fails validation with a prompt to select it again, so a document cannot be published with an icon that renders as nothing.
 
 <br />
 
-## Keeping the Icon Set Current
+### API
 
-The plugin tracks Lucide within its major version, so new icons arrive without waiting for a plugin release. Your lockfile pins whichever version resolved at install, and removing and re-adding the plugin resolves it afresh.
+| Export                     | Import from                           | Purpose                                  |
+| -------------------------- | ------------------------------------- | ---------------------------------------- |
+| `iconPlugin(config?)`      | `@driftime/sanity-plugin-icon`        | Registers the `icon` type.               |
+| `createIconPreview(value)` | `@driftime/sanity-plugin-icon`        | Builds preview media from a stored icon. |
+| `Icon`                     | `@driftime/sanity-plugin-icon/render` | Draws a stored icon.                     |
 
-```bash
-bun remove @driftime/sanity-plugin-icon
-bun add -E @driftime/sanity-plugin-icon
-```
+<br />
+
+### Types
 
-`bun update lucide-static` also works, and adds the icon library to your own dependencies so you control the version from then on.
+| Type                   | Import from                           | Purpose                                                          |
+| ---------------------- | ------------------------------------- | ---------------------------------------------------------------- |
+| `SanityIconConfig`     | `@driftime/sanity-plugin-icon`        | Everything `iconPlugin` accepts.                                 |
+| `SanityIconOptions`    | `@driftime/sanity-plugin-icon`        | The `options` an icon field accepts.                             |
+| `SanityIconDefinition` | `@driftime/sanity-plugin-icon`        | A field or array member of type `icon`.                          |
+| `SanityIconName`       | `@driftime/sanity-plugin-icon`        | The name of an icon in the installed Lucide release.             |
+| `SanityIconProps`      | `@driftime/sanity-plugin-icon/render` | Everything `Icon` accepts: an `svg` element's props and `value`. |
+| `SanityIcon`           | `@driftime/sanity-plugin-icon/render` | A stored icon, with its name and its drawing.                    |
 
 <br />
 
-## API
+## License
 
-| Export                     | Import from                           | Purpose                                    |
-| -------------------------- | ------------------------------------- | ------------------------------------------ |
-| `iconPlugin()`             | `@driftime/sanity-plugin-icon`        | Registers the `icon` type with the Studio. |
-| `createIconPreview(value)` | `@driftime/sanity-plugin-icon`        | Builds preview media from a stored icon.   |
-| `Icon`                     | `@driftime/sanity-plugin-icon/render` | Draws a stored icon.                       |
-| `SanityIcon`               | either                                | Type of the stored value.                  |
+MIT © [Driftime®](https://driftime.com). See [LICENSE](https://github.com/driftime/sanity-plugins/blob/main/LICENSE).
 
 <br />
 
 ## Acknowledgements
 
-Icons come from [Lucide](https://lucide.dev), distributed under the [ISC License](https://github.com/lucide-icons/lucide/blob/main/LICENSE). Icons for controls the Studio already draws come from `@sanity/icons` so they match their surroundings.
+Icons are from [Lucide](https://lucide.dev), distributed under the [ISC License](https://github.com/lucide-icons/lucide/blob/main/LICENSE). Icons for the Studio's own controls come from `@sanity/icons`, so they match the rest of the Studio.
 
 <br />
 <br />
@@ -190,7 +298,7 @@ Icons come from [Lucide](https://lucide.dev), distributed under the [ISC License
 <div align="center">
   <p><strong>Built alongside <a href="https://cairn.driftime.com">Cairn</a>, a starting point for responsible web experiences.</strong></p>
   <p>Part of a suite of Sanity Studio plugins by Driftime®</p>
-  <p><a href="https://github.com/driftime/sanity-plugin-handbook">Handbook</a> · <a href="https://github.com/driftime/sanity-plugin-icon">Icon</a></p>
+  <p><a href="https://github.com/driftime/sanity-plugins#readme">Sanity Plugins</a> · <a href="https://github.com/driftime/sanity-plugins/tree/main/packages/handbook#readme">Handbook</a> · <a href="https://github.com/driftime/sanity-plugins/tree/main/packages/icon#readme">Icon</a> · <a href="https://github.com/driftime/sanity-plugins/tree/main/packages/color#readme">Color</a> · <a href="https://github.com/driftime/sanity-plugins/tree/main/packages/link#readme">Link</a></p>
 </div>
 
 <br />

package/dist/{drawing-Bo0HTICv.js → drawing-BThiR2bN.js}

@@ -1,5 +1,5 @@
-import { jsx } from "react/jsx-runtime";
 import { createElement } from "react";
+import { jsx } from "react/jsx-runtime";
 import { stegaClean } from "@sanity/client/stega";
 /**
 * Checks whether a value is defined and non-empty, treating `false`, empty strings, and objects with
@@ -38,6 +38,15 @@ function convertCase(value, format) {
 		default: return value;
 	}
 }
+/**
+* Checks whether a value can be read by key, narrowing what arrives untyped from outside the plugin.
+*
+* @param value - The value to check.
+* @returns True if the value has keys to read.
+*/
+function isRecord(value) {
+	return typeof value == "object" && !!value;
+}
 /** Elements an icon's drawing may be built from, narrowed to those that describe a shape. */
 const iconElements = [
 	"circle",
@@ -67,7 +76,7 @@ const iconElements = [
 * @returns True if the value is a drawing.
 */
 function isIconNode(value) {
-	return Array.isArray(value) ? value.every((element) => Array.isArray(element) && element.length === 2 && iconElements.some((name) => name === element[0]) && typeof element[1] == "object" && element[1] !== null) : !1;
+	return Array.isArray(value) ? value.every((element) => Array.isArray(element) && element.length === 2 && iconElements.some((name) => name === element[0]) && isRecord(element[1])) : !1;
 }
 /**
 * Reads an icon's drawing from an already-parsed value, for a library handing over its drawings as
@@ -101,7 +110,7 @@ function resolveIconNode(value) {
 * @param node - The drawing to store.
 * @returns The drawing ready to store.
 */
-function serialiseIconNode(node) {
+function serializeIconNode(node) {
 	return JSON.stringify(node);
 }
 function Drawing({ node, ...props }) {
@@ -115,6 +124,6 @@ function Drawing({ node, ...props }) {
 		}))
 	}) : null;
 }
-export { convertCase as a, serialiseIconNode as i, parseIconNode as n, isDefined as o, resolveIconNode as r, Drawing as t };
+export { convertCase as a, serializeIconNode as i, parseIconNode as n, isDefined as o, resolveIconNode as r, Drawing as t };
 
-//# sourceMappingURL=drawing-Bo0HTICv.js.map
+//# sourceMappingURL=drawing-BThiR2bN.js.map

package/dist/drawing-BThiR2bN.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drawing-BThiR2bN.js","names":["Nullable","T","isDefined","value","undefined","trim","Array","isArray","some","element","prototype","Reflect","getPrototypeOf","Object","keys","length","convertCase","format","words","replaceAll","toLowerCase","_match","character","toUpperCase","isRecord","Record","readPath","path","current","segment","isDefined","isRecord","stegaClean","iconElements","const","IconElement","element","attributes","Record","IconNode","iconRootAttributes","xmlns","width","height","viewBox","fill","stroke","strokeWidth","strokeLinecap","strokeLinejoin","isIconNode","value","Array","isArray","every","length","some","name","parseIconNode","undefined","resolveIconNode","cleaned","parsed","JSON","parse","serializeIconNode","node","stringify","isDefined","ComponentProps","createElement","IconNode","iconRootAttributes","DrawingProps","Omit","node","Drawing","props","map","element","attributes","index","key","String"],"sources":["../../@repo/lib/utils.ts","../src/lib/nodes.ts","../src/components/drawing.tsx"],"sourcesContent":["/** A value that may be absent, covering both null and undefined. */\ntype Nullable<T> = T | null | undefined;\n\n/**\n * Checks whether a value is defined and non-empty, treating `false`, empty strings, and objects with\n * no keys as absent. An array is absent unless one of its elements is itself present, while anything\n * built from a class counts as present on existence alone. Not intended for boolean flags.\n *\n * @param value - The value to check.\n * @returns True if the value is defined and not empty.\n */\nexport function isDefined<T>(value: Nullable<T> | false): value is T {\n  if (value === undefined || value === null || value === false) return false;\n  if (typeof value === \"string\") return value.trim() !== \"\";\n  if (Array.isArray(value)) return value.some((element) => isDefined(element));\n\n  if (typeof value === \"object\") {\n    const prototype = Reflect.getPrototypeOf(value);\n    if (prototype !== Object.prototype && prototype !== null) return true;\n\n    return Object.keys(value).length > 0;\n  }\n\n  return true;\n}\n\n/**\n * Converts a string between different casing formats.\n *\n * @param value - The string to convert.\n * @param format - The target casing format.\n * @returns The converted string.\n */\nexport function convertCase(value: string, format: \"kebab\" | \"snake\" | \"camel\" | \"pascal\" | \"title\" | \"sentence\") {\n  const words = value\n    .replaceAll(/(?<lower>[a-z0-9])(?<upper>[A-Z])/gu, \"$<lower> $<upper>\")\n    .replaceAll(/[-_\\s]+/gu, \" \")\n    .trim()\n    .toLowerCase();\n\n  switch (format) {\n    case \"kebab\": {\n      return words.replaceAll(/\\s+/gu, \"-\");\n    }\n    case \"snake\": {\n      return words.replaceAll(/\\s+/gu, \"_\");\n    }\n    case \"camel\": {\n      return words.replaceAll(/\\s+(?<character>.)/gu, (_match, character: string) => character.toUpperCase());\n    }\n    case \"pascal\": {\n      return words.replaceAll(/(?:^|\\s+)(?<character>.)/gu, (_match, character: string) => character.toUpperCase());\n    }\n    case \"title\": {\n      return words.replaceAll(/\\b\\w/gu, (character) => character.toUpperCase());\n    }\n    case \"sentence\": {\n      return words.replaceAll(/^(?<character>.)/gu, (character) => character.toUpperCase());\n    }\n    default: {\n      return value;\n    }\n  }\n}\n\n/**\n * Checks whether a value can be read by key, narrowing what arrives untyped from outside the plugin.\n *\n * @param value - The value to check.\n * @returns True if the value has keys to read.\n */\nexport function isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null;\n}\n\n/**\n * Reads a value out of nested records by following a path of keys, so a caller can name something\n * inside a shape it does not otherwise know.\n *\n * @param value - The object to read from.\n * @param path - Keys leading to the value.\n * @returns The value at the path, or undefined when a key is missing or a step holds no keys to read.\n */\nexport function readPath(value: unknown, path: string[]) {\n  let current: unknown = value;\n\n  for (const segment of path) {\n    if (!isRecord(current)) return undefined;\n\n    current = current[segment];\n  }\n\n  return current;\n}\n","import { isDefined, isRecord } from \"@repo/lib/utils\";\nimport { stegaClean } from \"@sanity/client/stega\";\n\n/** Elements an icon's drawing may be built from, narrowed to those that describe a shape. */\nconst iconElements = [\"circle\", \"ellipse\", \"g\", \"line\", \"path\", \"polygon\", \"polyline\", \"rect\"] as const;\n\n/** Single shape in an icon's drawing, paired with the attributes it is drawn with. */\ntype IconElement = [element: (typeof iconElements)[number], attributes: Record<string, string>];\n\n/** An icon's drawing, held as the shapes it is built from rather than as a component. */\nexport type IconNode = IconElement[];\n\n/**\n * Attributes given to the SVG an icon's shapes are drawn inside, mirroring the grid and stroke Lucide\n * draws on. A library working to different conventions would need its own frame, which is why a\n * stored icon carries only what sits inside this one.\n */\nexport const iconRootAttributes = {\n  xmlns: \"http://www.w3.org/2000/svg\",\n  width: 24,\n  height: 24,\n  viewBox: \"0 0 24 24\",\n  fill: \"none\",\n  stroke: \"currentColor\",\n  strokeWidth: 2,\n  strokeLinecap: \"round\",\n  strokeLinejoin: \"round\",\n} as const;\n\n/**\n * Checks whether a parsed value is an icon's drawing, since it arrives as whatever happened to be\n * stored. Shapes are matched against the known elements so nothing else reaches the renderer.\n *\n * @param value - The value to check.\n * @returns True if the value is a drawing.\n */\nfunction isIconNode(value: unknown): value is IconNode {\n  if (!Array.isArray(value)) return false;\n\n  return value.every(\n    (element: unknown) =>\n      Array.isArray(element) &&\n      element.length === 2 &&\n      iconElements.some((name) => name === element[0]) &&\n      isRecord(element[1]),\n  );\n}\n\n/**\n * Reads an icon's drawing from an already-parsed value, for a library handing over its drawings as\n * data rather than as a document field.\n *\n * @param value - The value to read.\n * @returns The drawing, or undefined when the value is not one.\n */\nexport function parseIconNode(value: unknown) {\n  return isIconNode(value) ? value : undefined;\n}\n\n/**\n * Reads an icon's drawing back from the form it is stored in, clearing the stega characters a Sanity\n * fetch leaves behind.\n *\n * @param value - The stored drawing.\n * @returns The drawing, or undefined when nothing readable was stored.\n */\nexport function resolveIconNode(value: string | undefined) {\n  const cleaned = stegaClean(value);\n  if (!isDefined(cleaned)) return undefined;\n\n  try {\n    const parsed: unknown = JSON.parse(cleaned);\n\n    return parseIconNode(parsed);\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Writes an icon's drawing into the form it is stored in, so the shapes survive a round trip through\n * a document rather than a component reference that only resolves at build time.\n *\n * @param node - The drawing to store.\n * @returns The drawing ready to store.\n */\nexport function serializeIconNode(node: IconNode) {\n  return JSON.stringify(node);\n}\n","// Runs inside a consumer's server components, where the compiler's memo cache hook cannot.\n\"use no memo\";\n\nimport { isDefined } from \"@repo/lib/utils\";\nimport type { ComponentProps } from \"react\";\nimport { createElement } from \"react\";\n\nimport type { IconNode } from \"@/lib/nodes\";\nimport { iconRootAttributes } from \"@/lib/nodes\";\n\nexport type DrawingProps = Omit<ComponentProps<\"svg\">, \"children\"> & { node: IconNode | undefined };\n\nexport function Drawing({ node, ...props }: DrawingProps) {\n  if (!isDefined(node)) return null;\n\n  return (\n    <svg {...iconRootAttributes} aria-hidden=\"true\" {...props}>\n      {node.map(([element, attributes], index) => createElement(element, { ...attributes, key: String(index) }))}\n    </svg>\n  );\n}\n"],"mappings":";;;;;;;;;;;AAWA,SAAgBE,UAAaC,OAAwC;CACnE,IAAIA,SAAiC,QAAQA,UAAU,IAAO,OAAO;CACrE,IAAI,OAAOA,SAAU,UAAU,OAAOA,MAAME,KAAK,MAAM;CACvD,IAAIC,MAAMC,QAAQJ,KAAK,GAAG,OAAOA,MAAMK,MAAMC,YAAYP,UAAUO,OAAO,CAAC;CAE3E,IAAI,OAAON,SAAU,UAAU;EAC7B,IAAMO,YAAYC,QAAQC,eAAeT,KAAK;EAG9C,OAFIO,cAAcG,OAAOH,aAAaA,cAAc,QAE7CG,OAAOC,KAAKX,KAAK,CAAC,CAACY,SAAS;CACrC;CAEA,OAAO;AACT;;;;;;;;AASA,SAAgBC,YAAYb,OAAec,QAAuE;CAChH,IAAMC,QAAQf,MACXgB,WAAW,uCAAuC,mBAAmB,CAAC,CACtEA,WAAW,aAAa,GAAG,CAAC,CAC5Bd,KAAK,CAAC,CACNe,YAAY;CAEf,QAAQH,QAAR;EACE,KAAK,SACH,OAAOC,MAAMC,WAAW,SAAS,GAAG;EAEtC,KAAK,SACH,OAAOD,MAAMC,WAAW,SAAS,GAAG;EAEtC,KAAK,SACH,OAAOD,MAAMC,WAAW,yBAAyBE,QAAQC,cAAsBA,UAAUC,YAAY,CAAC;EAExG,KAAK,UACH,OAAOL,MAAMC,WAAW,+BAA+BE,QAAQC,cAAsBA,UAAUC,YAAY,CAAC;EAE9G,KAAK,SACH,OAAOL,MAAMC,WAAW,WAAWG,cAAcA,UAAUC,YAAY,CAAC;EAE1E,KAAK,YACH,OAAOL,MAAMC,WAAW,uBAAuBG,cAAcA,UAAUC,YAAY,CAAC;EAEtF,SACE,OAAOpB;CAEX;AACF;;;;;;;AAQA,SAAgBqB,SAASrB,OAAkD;CACzE,OAAO,OAAOA,SAAU,cAAYA;AACtC;;ACrEA,MAAM8B,eAAe;CAAC;CAAU;CAAW;CAAK;CAAQ;CAAQ;CAAW;CAAY;AAAM,GAahFO,qBAAqB;CAChCC,OAAO;CACPC,OAAO;CACPC,QAAQ;CACRC,SAAS;CACTC,MAAM;CACNC,QAAQ;CACRC,aAAa;CACbC,eAAe;CACfC,gBAAgB;AAClB;;;;;;;;AASA,SAASC,WAAWC,OAAmC;CAGrD,OAFKC,MAAMC,QAAQF,KAAK,IAEjBA,MAAMG,OACVlB,YACCgB,MAAMC,QAAQjB,OAAO,KACrBA,QAAQmB,WAAW,KACnBtB,aAAauB,MAAMC,SAASA,SAASrB,QAAQ,EAAE,KAC/CL,SAASK,QAAQ,EAAE,CACvB,IARkC;AASpC;;;;;;;;AASA,SAAgBsB,cAAcP,OAAgB;CAC5C,OAAOD,WAAWC,KAAK,IAAIA,QAAQQ,KAAAA;AACrC;;;;;;;;AASA,SAAgBC,gBAAgBT,OAA2B;CACzD,IAAMU,UAAU7B,WAAWmB,KAAK;CAC3BrB,cAAU+B,OAAO,GAEtB,IAAI;EAGF,OAAOH,cAFiBK,KAAKC,MAAMH,OAEdC,CAAM;CAC7B,QAAQ;EACN;CACF;AACF;;;;;;;;AASA,SAAgBG,kBAAkBC,MAAgB;CAChD,OAAOH,KAAKI,UAAUD,IAAI;AAC5B;AC5EA,SAAgBU,QAAQ,EAAED,MAAM,GAAGE,SAAuB;CAGxD,OAFKT,UAAUO,IAAI,IAGjB,oBAAC,OAAD;EAAK,GAAIH;EAAoB,eAAY;EAAO,GAAIK;EACjDF,UAAAA,KAAKG,KAAK,CAACC,SAASC,aAAaC,UAAUX,cAAcS,SAAS;GAAE,GAAGC;GAAYE,KAAKC,OAAOF,KAAK;EAAE,CAAC,CAAC;CACtG,CAAA,IALsB;AAO/B"}

package/dist/index.d.ts

@@ -1,12 +1,64 @@
-import { t as SanityIcon } from "./types-nQUVfUHK.js";
+import { n as iconTypeName, t as SanityIcon } from "./types-_D2jGm25.js";
+import { ObjectOptions, TypeAliasDefinition } from "sanity";
+import { ComponentProps } from "react";
+import iconNodes from "lucide-static/icon-nodes.json";
+declare module "@sanity/types" {
+  interface IntrinsicDefinitions {
+    icon: SanityIconDefinition;
+  }
+}
+/**
+ * Names of every icon the library offers, read from the Lucide release a project resolved rather than
+ * from a list this plugin ships, so an icon added since the last plugin release still completes.
+ *
+ * @public
+ */
+type SanityIconName = keyof typeof iconNodes;
+/**
+ * Options an icon field takes, narrowing what its picker offers.
+ *
+ * @public
+ */
+interface SanityIconOptions extends ObjectOptions {
+  /** Icons an author may choose from, offered in the order they are named. Every icon when omitted. */
+  icons?: SanityIconName[];
+}
+/**
+ * Shape of a field or array member holding an icon, so its options are completed and checked the way
+ * a built-in type's are.
+ *
+ * @public
+ */
+interface SanityIconDefinition extends Omit<TypeAliasDefinition<typeof iconTypeName, undefined>, "options"> {
+  options?: SanityIconOptions;
+}
+/**
+ * Everything the plugin accepts, all of which may be left out.
+ *
+ * @public
+ */
+interface SanityIconConfig {
+  /** Icons an author may choose from, offered in the order they are named. Every icon when omitted. */
+  icons?: SanityIconName[];
+}
 /**
  * Creates the icon field type for Sanity Studio, offering the Lucide library through a searchable
  * picker and storing the chosen drawing ready to render.
  *
+ * @param config - Plugin configuration.
  * @returns Sanity plugin definition.
  * @public
  */
-declare const iconPlugin: import("sanity").Plugin<void>;
+export declare function iconPlugin(config?: SanityIconConfig): import("sanity").PluginOptions;
+/** Elements an icon's drawing may be built from, narrowed to those that describe a shape. */
+declare const iconElements: readonly ["circle", "ellipse", "g", "line", "path", "polygon", "polyline", "rect"];
+/** Single shape in an icon's drawing, paired with the attributes it is drawn with. */
+type IconElement = [element: (typeof iconElements)[number], attributes: Record<string, string>];
+/** An icon's drawing, held as the shapes it is built from rather than as a component. */
+type IconNode = IconElement[];
+type DrawingProps = Omit<ComponentProps<"svg">, "children"> & {
+  node: IconNode | undefined;
+};
 /**
  * Builds the media a stored icon previews with, so a document lists the drawing an author chose
  * rather than one placeholder standing in for every icon alike.
@@ -15,6 +67,6 @@ declare const iconPlugin: import("sanity").Plugin<void>;
  * @returns The media component, or undefined when nothing readable was stored.
  * @public
  */
-declare function createIconPreview(value: SanityIcon | undefined): (() => import("react").JSX.Element) | undefined;
-export { type SanityIcon, createIconPreview, iconPlugin };
+export declare function createIconPreview(value: SanityIcon | undefined): (() => import("react").FunctionComponentElement<DrawingProps>) | undefined;
+export type { SanityIconConfig, SanityIconDefinition, SanityIconName, SanityIconOptions };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/plugin.ts","../src/components/preview.tsx"],"mappings":";;;;;;;;cAWa,6BAAU;;;;;;;;;iBCGP,kBAAkB,OAAO,gDAAsB,IAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/plugin.ts","../src/lib/nodes.ts","../src/components/drawing.tsx","../src/lib/preview.ts"],"mappings":";;;;;YAQY;IACR,MAAM;;;;;;;;;KAUE,8BAA8B;;;;;;UAOzB,0BAA0B;;EAEzC,QAAQ;;;;;;;;UASO,6BAA6B,KAAK,2BAA2B;EAC5E,UAAU;;;;;;;UAQK;;EAEf,QAAQ;;;;;;;;;;wBAkBM,WAAW,SAAQ,oCAAqB;;cC9DlD;;KAGD,eAAe,iBAAiB,uBAAuB,YAAY;;KAG5D,WAAW;KCAX,eAAe,KAAK;EAAuC,MAAM;;;;;;;;;;wBCM7D,kBAAkB,OAAO,gDAAsB,yBAAtB"}