[feature] (provider/directus) Add Sharp transforms to modifiers, add support for `key`ed transforms

[kheiner]

The current implementation of Directus Transforms is not typed appropriately, and not checked against any available functions. Directus uses Sharp on the backend, but not all functions work. There is also no implementation of the keyed transform option available in Directus.

The proposed enhancement should consider:

• (feature): Support for Keyed Transforms using the key string, stripping all other transforms supported by Nuxt/Image
  • (test): Ensure that key if present is not paired with other modifiers.
  • (playground): Identify Directus instance that has pre-configured keys in the public space for better explanation to developers.
    • Option 1: https://sandbox.directus.io using key=800w or key=1200w. (customized transforms)
    • Option 2: using key=system-[small/medium/large]-[cover/contain]
• (feature): Transforms should have typing for Image Operations, Color Manipulation, and Channel Manipulation as supported by Sharp.
• (fix): The current transforms are typed as string[] which is not valid. Transforms should fallback to a tuple of type [string, ...any[]][] to prevent errors with using transforms not typed explicitly. (Future proofing for new transforms added to Sharp & supported by Directus.)
• (docs): Update Docs ->
  • Provide a note that key requires setup in Directus. (Not actually true, see comment below)
  • Explicitly name Sharp Transforms that are supported (and link to details in Sharp Library)

I don't think this will break anything for existing users.

[kheiner]

The Directus SDK is typed as:

export type AssetsQuery =
    | { key: string }
    | {
            key?: never;
            fit?: 'cover' | 'contain' | 'inside' | 'outside';
            width?: number;
            height?: number;
            quality?: number;
            withoutEnlargement?: boolean;
            format?: 'auto' | 'jpg' | 'png' | 'webp' | 'tiff';
            focal_point_x?: number;
            focal_point_y?: number;
            transforms?: [string, ...any[]][];
      };

The Sharp Transform Types in Directus are:

export const TransformationMethods /*: readonly (keyof Sharp)[]*/ = [
    // Output options
    // https://sharp.pixelplumbing.com/api-output
    'toFormat',
    'jpeg',
    'png',
    'tiff',
    'webp',
    'avif',

    // Resizing
    // https://sharp.pixelplumbing.com/api-resize
    'resize',
    'extend',
    'extract',
    'trim',

    // Image operations
    // https://sharp.pixelplumbing.com/api-operation
    'rotate',
    'flip',
    'flop',
    'sharpen',
    'median',
    'blur',
    'flatten',
    'gamma',
    'negate',
    'normalise',
    'normalize',
    'clahe',
    'convolve',
    'threshold',
    'linear',
    'recomb',
    'modulate',

    // Color manipulation
    // https://sharp.pixelplumbing.com/api-colour
    'tint',
    'greyscale',
    'grayscale',
    'toColorspace',
    'toColourspace',

    // Channel manipulation
    // https://sharp.pixelplumbing.com/api-channel
    'removeAlpha',
    'ensureAlpha',
    'extractChannel',
    'bandbool',
] as const;

[kheiner]

I found a live sandbox for Directus that is configured with keys that can be used to test for Keyed Transformations. The currently configured key transformations are 800w and 1200w.
There are default keyed transforms since Directus 11.17.2

export const SYSTEM_ASSET_ALLOW_LIST: TransformationParams[] = [
    {
        key: 'system-small-cover',
        format: 'auto',
        transforms: [['resize', { width: 64, height: 64, fit: 'cover' }]],
    },
    {
        key: 'system-small-contain',
        format: 'auto',
        transforms: [['resize', { width: 64, fit: 'contain' }]],
    },
    {
        key: 'system-medium-cover',
        format: 'auto',
        transforms: [['resize', { width: 300, height: 300, fit: 'cover' }]],
    },
    {
        key: 'system-medium-contain',
        format: 'auto',
        transforms: [['resize', { width: 300, fit: 'contain' }]],
    },
    {
        key: 'system-large-cover',
        format: 'auto',
        transforms: [['resize', { width: 800, height: 800, fit: 'cover' }]],
    },
    {
        key: 'system-large-contain',
        format: 'auto',
        transforms: [['resize', { width: 800, fit: 'contain' }]],
    },
];

Note that the configuration of the Directus instance dictates the maximum amount of Transforms that can be processed with a default of 5.