@driftime/sanity-plugin-icon 0.1.0 → 0.2.0

package/README.md

@@ -13,7 +13,7 @@
 
 ## 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.
+Icon adds a field type to Sanity Studio that opens the Lucide library as a searchable grid, either in full or limited to a set you choose. 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.
 
 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.
 
@@ -42,7 +42,7 @@ bun add -E @driftime/sanity-plugin-icon
 
 ## Basic Setup
 
-Add the plugin to your Sanity configuration. It takes no options.
+Add the plugin to your Sanity configuration.
 
 ```typescript
 import { defineConfig } from "sanity";
@@ -67,12 +67,50 @@ defineField({
 
 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.
 
+See [Configuration](#configuration) for the options the plugin takes.
+
+<br />
+
+## Restricting the Icon Set
+
+By default the picker offers every icon in the library. Pass `icons` to limit it, and every field takes the set you name.
+
+```typescript
+export default defineConfig({
+  // ...
+  plugins: [iconPlugin({ icons: ["mail", "phone", "globe"] })],
+});
+```
+
+The plugin augments Sanity's `IntrinsicDefinitions` interface, adding an `icons` option that TypeScript recognises automatically. A field can name its own set, which replaces the one the plugin was given rather than narrowing it.
+
+```typescript
+defineField({
+  name: "icon",
+  type: "icon",
+  description: "Shown on the feature card.",
+  options: { icons: ["leaf", "shield", "zap"] },
+});
+```
+
+Names are typed against the Lucide version your project resolved, so they autocomplete as you write them. Icons appear in the order you list them, and a name that version does not recognise is skipped.
+
+Use `SanityIconName` to type a set you want to share between fields.
+
+```typescript
+import type { SanityIconName } from "@driftime/sanity-plugin-icon";
+
+export const clientIcons: SanityIconName[] = ["mail", "phone", "globe"];
+```
+
+Restricting a set does not affect what has already been stored. The document holds the drawing, so an icon saved earlier still renders even though the picker no longer offers it.
+
 <br />
 
 ## Picking an 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 complete Lucide set is offered unless you restrict it, and the count reflects whatever is available.
 - The last eight icons chosen are remembered, per browser rather than per dataset.
 
 <br />
@@ -171,12 +209,46 @@ bun add -E @driftime/sanity-plugin-icon
 
 ## API
 
+What the package exports at runtime, and which import path each one comes from.
+
 | Export                     | Import from                           | Purpose                                    |
 | -------------------------- | ------------------------------------- | ------------------------------------------ |
-| `iconPlugin()`             | `@driftime/sanity-plugin-icon`        | Registers the `icon` type with the Studio. |
+| `iconPlugin(config?)`      | `@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.                  |
+
+<br />
+
+## Configuration
+
+Nothing is required. Without `icons`, the picker offers every icon in the library.
+
+| Option  | Type               | Default     | Purpose                                                                                 |
+| ------- | ------------------ | ----------- | --------------------------------------------------------------------------------------- |
+| `icons` | `SanityIconName[]` | `undefined` | Icons an author may choose from, in the order they are listed. Every icon when omitted. |
+
+A field accepts the same option under `options`, where it replaces the set the plugin was given.
+
+<br />
+
+## Exported Types
+
+These types are exported for typing your own configuration and for querying stored icons outside the Studio.
+
+Configuration you supply:
+
+| Type                   | Purpose                                                 |
+| ---------------------- | ------------------------------------------------------- |
+| `SanityIconName`       | The name of an icon in the installed Lucide version.    |
+| `SanityIconOptions`    | The `options` an icon field accepts.                    |
+| `SanityIconDefinition` | The shape of a field or array member of type `icon`.    |
+| `SanityIconConfig`     | The full plugin configuration accepted by `iconPlugin`. |
+
+Content the dataset stores:
+
+| Type         | Purpose                                                                                                      |
+| ------------ | ------------------------------------------------------------------------------------------------------------ |
+| `SanityIcon` | A stored icon, holding the name it was chosen by and the shapes it draws. Available from either import path. |
 
 <br />
 

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>;
+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 };
+declare function createIconPreview(value: SanityIcon | undefined): (() => import("react").FunctionComponentElement<DrawingProps>) | undefined;
+export { type SanityIcon, type SanityIconConfig, type SanityIconDefinition, type SanityIconName, type SanityIconOptions, createIconPreview, iconPlugin };
 //# 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;;;;;;;;;;iBAuBM,WAAW,SAAQ,oCAAqB;;cClElD;;KAGD,eAAe,iBAAiB,uBAAuB,YAAY;;KAG5D,WAAW;KCDX,eAAe,KAAK;EAAuC,MAAM;;;;;;;;;;iBCM7D,kBAAkB,OAAO,gDAAsB,yBAAtB"}