@electrolux-oss/sanity-plugin-media 5.0.1 → 5.1.0

package/README.md

@@ -223,7 +223,18 @@ The plugin adds an **Edit Media** option to the asset menu of image and file fie
 
 ### Link the plugin to a local studio
 
-**Step 1: Set up the plugin for local development**
+**Step 1: Install the studio's dependencies**
+
+In your studio project directory, run:
+
+```zsh
+npm install
+```
+
+This installs the published version of the plugin, so its own dependencies end up in the
+studio's `node_modules`.
+
+**Step 2: Publish the plugin to yalc and watch for changes**
 
 In the plugin directory, run:
 
@@ -234,29 +245,33 @@ npm run link-watch
 This will:
 
 - Build your plugin automatically whenever code changes
-- Publish the package to a local yalc repository
+- Publish the package to a local yalc repository and push it to linked studios
 
-**Step 2: Link the plugin to your studio**
+**Step 3: Link the plugin to your studio**
 
 In your studio project directory, run:
 
 ```zsh
-npx yalc add @electrolux-oss/sanity-plugin-media && npm install
+npx yalc link @electrolux-oss/sanity-plugin-media
 ```
 
-**Step 3: Verify the setup**
+**Step 4: Verify the setup**
 
-Check your studio's `package.json` - you should see:
+`node_modules/@electrolux-oss/sanity-plugin-media` is now a symlink to
+`.yalc/@electrolux-oss/sanity-plugin-media`, and the studio's `package.json` is unchanged:
 
-```json
-"@electrolux-oss/sanity-plugin-media": "file:.yalc/@electrolux-oss/sanity-plugin-media"
+```zsh
+ls -l node_modules/@electrolux-oss/
+git diff package.json   # no change
 ```
 
-Now you can use the local version of the plugin:
+Don't run `npm install` in the studio while linked: it replaces the link with the published
+version. Run `npx yalc link @electrolux-oss/sanity-plugin-media` again if you did. To stop,
+run `npx yalc remove @electrolux-oss/sanity-plugin-media && npm install`.
 
-```typescript
-import { media } from '@electrolux-oss/sanity-plugin-media'
-```
+Avoid `yalc add` here. It writes `file:.yalc/…` into the studio's `package.json`, and with
+`link-watch` every rebuild replaces the plugin with a copy that can't resolve the plugin's own
+dependencies.
 
 ### Making changes
 
@@ -268,12 +283,46 @@ serves the old build.
 
 ```zsh
 npm run typecheck # tsc --noEmit
-npm run lint      # ESLint
-npm run build     # also fails on type errors
+npm run lint      # oxlint, type-aware; warnings count as errors
+npm run format    # oxfmt
+npm run build     # plugin-kit verify-package, then pkg-utils
 ```
 
 This plugin has no automated tests yet.
 
+`npm run build` doesn't type-check (pkg-utils 13 generates types without checking them), so
+run `typecheck` or `lint` to catch type errors.
+
+### Formatting
+
+The plugin is formatted with [oxfmt](https://oxc.rs/docs/guide/usage/formatter.html), using
+plugin-kit's preset with the repository's previous Prettier settings on top (see
+`oxfmt.config.ts`). To format on save in VS Code, install the
+[Oxc extension](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode) and make it
+the default formatter for this workspace; a global Prettier formatter would undo oxfmt's
+import and `package.json` sorting.
+
+### Publishing
+
+Releases are published with pnpm, while development uses npm:
+
+```zsh
+npm run publish:next:dry-run   # what would ship
+npm run publish:next           # publish behind the next tag
+```
+
+pnpm is a pinned devDependency, so `npm ci` installs it. Don't use `npm publish`.
+
+pkg-utils writes a `source` condition into `exports` for local development and a
+`source`-less `publishConfig.exports` for the published package. pnpm applies
+`publishConfig` when it packs the package; npm doesn't, and would publish an export that points
+at `src/`, which isn't shipped. To check what the packed `package.json` exports:
+
+```zsh
+D=$(mktemp -d) && npx pnpm pack --pack-destination "$D" >/dev/null && tar xzf "$D"/*.tgz -C "$D" && node -p "JSON.stringify(require('$D/package/package.json').exports)"
+# -> {".":"./dist/index.js","./package.json":"./package.json"}, no "source"
+```
+
 ## Breaking changes
 
 ### **v4 → v5**

package/dist/index.d.ts

@@ -1,221 +1,158 @@
-import { AssetSourceComponentProps } from 'sanity'
-import type { ComponentType } from 'react'
-import type { Control } from 'react-hook-form'
-import type { FieldDefinitionBase } from 'sanity'
-import type { FieldErrors } from 'react-hook-form'
-import type { FileDefinition } from 'sanity'
-import { ForwardRefExoticComponent } from 'react'
-import type { ImageDefinition } from 'sanity'
-import type { InputProps } from 'sanity'
-import { JSX } from 'react'
-import { Plugin as Plugin_2 } from 'sanity'
-import { RefAttributes } from 'react'
-import type { SanityAssetDocument } from '@sanity/client'
-import type { SanityImageAssetDocument } from '@sanity/client'
-import { SVGProps } from 'react'
-import type { UseFormRegister } from 'react-hook-form'
-import type { WidenInitialValue } from 'sanity'
-import type { WidenValidation } from 'sanity'
-import * as z from 'zod'
-
-declare type Asset = FileAsset | ImageAsset
-
-declare type AssetFormData = z.infer<AssetFormSchemaObject>
-
-declare type AssetFormSchemaObject = ReturnType<typeof createAssetFormSchema>
-
-/**
- * Image / file input that tags the selected or uploaded asset with `mediaTags`.
- *
- * Tags come from the `mediaTags` prop, falling back to `options.mediaTags` on the field
- * (which also pre-filters the media browser). Only changes made after mount are tagged,
- * so opening a document never patches its existing assets.
- */
-export declare function AutoTagInput(props: AutoTagInputProps): JSX
-
-export declare type AutoTagInputProps = InputProps & {
-  mediaTags?: string[]
-}
-
-declare const createAssetFormSchema: (
-  languages: MediaToolOptions['languages'],
-  validateAltTexts?: boolean
-) => z.ZodObject<
-  {
-    altText: z.ZodOptional<z.ZodString>
-    altTexts: z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodNullable<z.ZodString>>>
-    creditLine: z.ZodOptional<z.ZodString>
-    description: z.ZodOptional<z.ZodString>
-    opt: z.ZodObject<
-      {
-        media: z.ZodObject<
-          {
-            tags: z.ZodNullable<
-              z.ZodArray<
-                z.ZodObject<
-                  {
-                    label: z.ZodString
-                    value: z.ZodString
-                  },
-                  z.core.$strip
-                >
-              >
-            >
-          },
-          z.core.$strip
-        >
-      },
-      z.core.$strip
-    >
-    originalFilename: z.ZodString
-    title: z.ZodOptional<z.ZodString>
-  },
-  z.core.$strip
->
-
-declare type CustomFields = {
-  altText?: string
-  altTexts?: Record<string, string>
-  description?: string
-  opt?: {
-    media?: {
-      tags?: SanityReference[]
-      uploadedBy?: Uploader | string
-    }
-  }
-  title?: string
-}
-
-declare type DetailsProps = {
-  formUpdating: boolean
-  handleCreateTag: (title: string) => void
-  control: Control<AssetFormData>
-  errors: FieldErrors<AssetFormData>
-  register: UseFormRegister<AssetFormData>
-  allTagOptions: TagSelectOption[]
-  assetTagOptions: TagSelectOption[] | null
-  currentAsset: Asset
+import { ComponentType, JSX } from "react";
+import { FieldDefinitionBase, FileDefinition, ImageDefinition, InputProps, WidenInitialValue, WidenValidation } from "sanity";
+import * as z from "zod";
+import "react-redux";
+import "@reduxjs/toolkit";
+import "redux-observable";
+import { Control, FieldErrors, UseFormRegister } from "react-hook-form";
+import { SanityAssetDocument, SanityImageAssetDocument } from "@sanity/client";
+declare const tagOptionSchema: z.ZodObject<{
+  label: z.ZodString;
+  value: z.ZodString;
+}, z.core.$strip>;
+declare const createAssetFormSchema: (languages: MediaToolOptions["languages"], validateAltTexts?: boolean) => z.ZodObject<{
+  altText: z.ZodOptional<z.ZodString>;
+  altTexts: z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+  creditLine: z.ZodOptional<z.ZodString>;
+  description: z.ZodOptional<z.ZodString>;
+  opt: z.ZodObject<{
+    media: z.ZodObject<{
+      tags: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodString;
+      }, z.core.$strip>>>;
+    }, z.core.$strip>;
+  }, z.core.$strip>;
+  originalFilename: z.ZodString;
+  title: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type AssetFormSchemaObject = ReturnType<typeof createAssetFormSchema>;
+type DetailsProps = {
+  formUpdating: boolean;
+  handleCreateTag: (title: string) => void;
+  control: Control<AssetFormData>;
+  errors: FieldErrors<AssetFormData>;
+  register: UseFormRegister<AssetFormData>;
+  allTagOptions: TagSelectOption[];
+  assetTagOptions: TagSelectOption[] | null;
+  currentAsset: Asset;
   creditLine?: {
-    enabled: boolean
-    excludeSources?: string | string[] | undefined
-  }
-}
-
-declare type FileAsset = SanityAssetDocument &
-  CustomFields & {
-    _type: 'sanity.fileAsset'
-  }
-
-declare type ImageAsset = SanityImageAssetDocument &
-  CustomFields & {
-    _type: 'sanity.imageAsset'
-    creditLine?: string
+    enabled: boolean;
+    excludeSources?: string | string[] | undefined;
+  };
+};
+declare global {
+  interface SymbolConstructor {
+    readonly observable: symbol;
   }
-
-export declare const media: Plugin_2<void | MediaToolOptions>
-
-export declare const mediaAssetSource: {
-  component: (props: AssetSourceComponentProps) => JSX
-  uploadMode: 'component'
-  icon: ForwardRefExoticComponent<
-    Omit<SVGProps<SVGSVGElement>, 'ref'> & RefAttributes<SVGSVGElement>
-  >
-  name: string
-  title: string
 }
-
-/**
- * Defines an image or file field whose selected / uploaded assets are tagged with `mediaTags`.
- *
- * `mediaTags` is copied to `options.mediaTags` (which pre-filters the media browser) and
- * {@link AutoTagInput} is set as the input component.
- *
- * ```ts
- * mediaField({ name: 'image', type: 'image', mediaTags: ['product'] })
- * ```
- */
-export declare function mediaField(
-  config: MediaFieldConfig<ImageDefinition>
-): MediaFieldResult<ImageDefinition>
-
-export declare function mediaField(
-  config: MediaFieldConfig<FileDefinition>
-): MediaFieldResult<FileDefinition>
-
-declare type MediaFieldConfig<T extends ImageDefinition | FileDefinition> = Omit<T, 'options'> &
-  FieldDefinitionBase & {
-    name: string
-    mediaTags: string[]
-    options?: T['options']
-  }
-
-declare type MediaFieldResult<T extends ImageDefinition | FileDefinition> = Omit<T, 'options'> &
-  FieldDefinitionBase & {
-    options?: T['options'] & {
-      mediaTags: string[]
-    }
-    components: {
-      input: typeof AutoTagInput
-    }
-  } & WidenValidation &
-  WidenInitialValue
-
-export declare type MediaToolOptions = {
+type MediaToolOptions = {
   languages: {
-    code: string
-    title: string
-    default?: boolean
-  }[]
-  maximumUploadSize?: number
-  createTagsOnUpload?: boolean
+    code: string;
+    title: string;
+    default?: boolean;
+  }[];
+  maximumUploadSize?: number;
+  createTagsOnUpload?: boolean;
   components?: {
-    details?: ComponentType<
-      DetailsProps & {
-        renderDefaultDetails: (props: DetailsProps) => JSX.Element
-      }
-    >
-  }
+    details?: ComponentType<DetailsProps & {
+      renderDefaultDetails: (props: DetailsProps) => JSX.Element;
+    }>;
+  };
   creditLine: {
-    enabled: boolean
-    excludeSources?: string | string[]
-  }
-  directUploads?: boolean
-  uploadMenu?: boolean
+    enabled: boolean;
+    excludeSources?: string | string[];
+  };
+  directUploads?: boolean;
+  uploadMenu?: boolean;
   /**
    * Tag slugs (`media.tag` `name.current`) whose assets are hidden from the Media browser and
    * asset picker, along with the tags themselves in the tag panel and tag search facet.
    * The asset edit dialog still lists every tag.
    */
-  excludeTags?: string[]
-}
-
-declare type SanityReference = {
-  _ref: string
-  _type: 'reference'
-  _weak?: boolean
-}
-
-declare const tagOptionSchema: z.ZodObject<
-  {
-    label: z.ZodString
-    value: z.ZodString
-  },
-  z.core.$strip
->
-
-declare type TagSelectOption = z.infer<typeof tagOptionSchema>
-
-declare type Uploader = {
-  id: string
+  excludeTags?: string[];
+};
+type Uploader = {
+  id: string;
   /** Only set by earlier builds; the name is now looked up on demand. */
-  name?: string
-}
-
-export {}
-
+  name?: string;
+};
+type CustomFields = {
+  altText?: string;
+  altTexts?: Record<string, string>;
+  description?: string;
+  opt?: {
+    media?: {
+      tags?: SanityReference[];
+      uploadedBy?: Uploader | string;
+    };
+  };
+  title?: string;
+};
+type Asset = FileAsset | ImageAsset;
+type AssetFormData = z.infer<AssetFormSchemaObject>;
+type FileAsset = SanityAssetDocument & CustomFields & {
+  _type: 'sanity.fileAsset';
+};
+type ImageAsset = SanityImageAssetDocument & CustomFields & {
+  _type: 'sanity.imageAsset';
+  creditLine?: string;
+};
+type SanityReference = {
+  _ref: string;
+  _type: 'reference';
+  _weak?: boolean;
+};
+type TagSelectOption = z.infer<typeof tagOptionSchema>;
 declare module 'sanity' {
   interface FileOptions {
     /** Tags applied by `AutoTagInput` / `mediaField`, also used to pre-filter the media browser. */
-    mediaTags?: string[]
+    mediaTags?: string[];
   }
 }
+export declare const mediaAssetSource: {
+  component: (props: import("sanity").AssetSourceComponentProps) => import("react/jsx-runtime").JSX.Element;
+  uploadMode: "component";
+  icon: import("react").ForwardRefExoticComponent<Omit<import("react").SVGProps<SVGSVGElement>, "ref"> & import("react").RefAttributes<SVGSVGElement>>;
+  name: string;
+  title: string;
+};
+export declare const media: import("sanity").Plugin<void | MediaToolOptions>;
+type AutoTagInputProps = InputProps & {
+  mediaTags?: string[];
+};
+/**
+ * Image / file input that tags the selected or uploaded asset with `mediaTags`.
+ *
+ * Tags come from the `mediaTags` prop, falling back to `options.mediaTags` on the field
+ * (which also pre-filters the media browser). Only changes made after mount are tagged,
+ * so opening a document never patches its existing assets.
+ */
+export declare function AutoTagInput(props: AutoTagInputProps): import("react").JSX.Element;
+type MediaFieldConfig<T extends ImageDefinition | FileDefinition> = Omit<T, 'options'> & FieldDefinitionBase & {
+  name: string;
+  mediaTags: string[];
+  options?: T['options'];
+};
+type MediaFieldResult<T extends ImageDefinition | FileDefinition> = Omit<T, 'options'> & FieldDefinitionBase & {
+  options?: T['options'] & {
+    mediaTags: string[];
+  };
+  components: {
+    input: typeof AutoTagInput;
+  };
+} & WidenValidation & WidenInitialValue;
+/**
+ * Defines an image or file field whose selected / uploaded assets are tagged with `mediaTags`.
+ *
+ * `mediaTags` is copied to `options.mediaTags` (which pre-filters the media browser) and
+ * {@link AutoTagInput} is set as the input component.
+ *
+ * ```ts
+ * mediaField({ name: 'image', type: 'image', mediaTags: ['product'] })
+ * ```
+ */
+export declare function mediaField(config: MediaFieldConfig<ImageDefinition>): MediaFieldResult<ImageDefinition>;
+export declare function mediaField(config: MediaFieldConfig<FileDefinition>): MediaFieldResult<FileDefinition>;
+export type { AutoTagInputProps, MediaToolOptions };
+//# sourceMappingURL=index.d.ts.map