@okam/directus-block 1.5.21 → 1.6.0

package/CHANGELOG.md

@@ -1,3 +1,46 @@
+## 1.6.0 (2025-10-17)
+
+### 🚀 Features
+
+- bump ([ab924b9](https://github.com/OKAMca/stack/commit/ab924b9))
+
+### 🩹 Fixes
+
+- **directus-block:** clean up useBlock type usage ([c7b198e](https://github.com/OKAMca/stack/commit/c7b198e))
+- **directus-block:** always pass type params between block serializer types ([430e6db](https://github.com/OKAMca/stack/commit/430e6db))
+- update vite-plugin-dts to version 3 ([5d33c77](https://github.com/OKAMca/stack/commit/5d33c77))
+- package deps error ([b665a45](https://github.com/OKAMca/stack/commit/b665a45))
+- search field type export ([5ab6070](https://github.com/OKAMca/stack/commit/5ab6070))
+- search field icon ([0850fde](https://github.com/OKAMca/stack/commit/0850fde))
+
+### ❤️ Thank You
+
+- Marie-Maxime Tanguay
+- Pierre-Olivier Clerson @poclerson
+- poclerson
+
+## 1.5.22 (2025-10-17)
+
+### 🚀 Features
+
+- bump ([ab924b9](https://github.com/OKAMca/stack/commit/ab924b9))
+
+### 🩹 Fixes
+
+- update vite-plugin-dts to version 3 ([5d33c77](https://github.com/OKAMca/stack/commit/5d33c77))
+- package deps error ([b665a45](https://github.com/OKAMca/stack/commit/b665a45))
+- search field type export ([5ab6070](https://github.com/OKAMca/stack/commit/5ab6070))
+- search field icon ([0850fde](https://github.com/OKAMca/stack/commit/0850fde))
+
+### 🧱 Updated Dependencies
+
+- Updated stack-ui to 1.42.3
+
+### ❤️ Thank You
+
+- Marie-Maxime Tanguay
+- Pierre-Olivier Clerson @poclerson
+
 ## 1.5.21 (2025-10-14)
 
 ### 🚀 Features

package/components/BlockSerializer/interface.d.ts

@@ -1,31 +1,97 @@
 import { type TypedDocumentNode } from '@graphql-typed-document-node/core';
 import type { Nullable, TDefaultComponent } from '@okam/stack-ui';
-import type { Variables } from 'graphql-request';
+import type { Variables as GraphQLVariables } from 'graphql-request';
 import type { FunctionComponent } from 'react';
 import type { TCommonBlockFragment, TAdditionalProps, TBlockQuery, TBlockVariables, TBlockDocument } from '../../types/block';
-export interface TBlock<BlockFragment extends TCommonBlockFragment = TCommonBlockFragment, BlockVariables extends Variables = Variables> {
+/**
+ * Base block data. See {@link TBlockSerializerProps} for actual props implementation.
+ */
+export interface TBlock<Fragment extends TCommonBlockFragment = TCommonBlockFragment, Variables extends GraphQLVariables = TBlockVariables> {
+    /**
+     * Directus collection name of the block.
+     */
     collection?: Nullable<string>;
-    item?: Nullable<BlockFragment>;
-    variables?: TBlockVariables<BlockVariables>;
-    document?: TypedDocumentNode<TBlockQuery<BlockFragment>, BlockVariables>;
+    /**
+     * The actual block's data. If only the id is passed, the block will be queried using the `variables` prop. Otherwise, the block will be passed as is.
+     */
+    item?: Nullable<Fragment>;
+    variables?: TBlockVariables<Variables>;
+    document?: TypedDocumentNode<TBlockQuery<Fragment>, Variables>;
 }
-export type TBlockSerializerProps<BlockFragment extends TCommonBlockFragment = TCommonBlockFragment, BlockVariables extends Variables = TBlockVariables, AdditionalProps extends TAdditionalProps = TAdditionalProps> = TBlock<BlockFragment, BlockVariables> & TDefaultComponent & {
+/**
+ * The props of individual block components.
+ * @template Fragment - The GraphQL fragment type for the block data structure
+ * @template Variables - The GraphQL variables type for querying the block
+ * @template AdditionalProps - Additional props that can be passed to the block component
+ */
+export type TBlockSerializerProps<Fragment extends TCommonBlockFragment = TCommonBlockFragment, Variables extends GraphQLVariables = TBlockVariables, AdditionalProps extends TAdditionalProps = TAdditionalProps> = TBlock<Fragment, Variables> & TDefaultComponent & {
     config?: TBlockSerializerConfig;
     defaultVariant?: string;
     additionalProps?: AdditionalProps;
 };
-export type TBlockFunctionComponent<BlockFragment extends TCommonBlockFragment = TCommonBlockFragment> = FunctionComponent<TBlockSerializerProps<BlockFragment>>;
-export type TBlockSerializerConfigComponent<BlockFragment extends TCommonBlockFragment = TCommonBlockFragment> = {
+/**
+ * Wrapper for {@link TBlockSerializerProps} to be used as a component type
+ */
+export type TBlockFunctionComponent<Fragment extends TCommonBlockFragment = TCommonBlockFragment, Variables extends GraphQLVariables = TBlockVariables, AdditionalProps extends TAdditionalProps = TAdditionalProps> = FunctionComponent<TBlockSerializerProps<Fragment, Variables, AdditionalProps>>;
+/**
+ * To make a component a part of the block serializer configuration, add its own key to the config object.
+ *
+ * ### Basic usage
+ * @example
+ * ```tsx
+ * const configComponent: TBlockSerializerConfigComponent = {
+ *   block_wysiwygs: {
+ *     default: (props) => <BlockWysiwygs {...props} />,
+ *   },
+ * }
+ * const config = {
+ *   components: {
+ *     ...configComponent,
+ *   },
+ * }
+ * ```
+ *
+ * ### Using variants with `variants`, `getVariant` and `defaultVariant`
+ * @example
+ * ```tsx
+ * const configComponent: TBlockSerializerConfigComponent<BlockButtonsFragment> = {
+ *   block_buttons: {
+ *     // Default is always required even if `defaultVariant` is passed since it's the fallback component
+ *     default: (props) => <BlockButtons {...props} />,
+ *     defaultVariant: 'primary',
+ *     // Some blocks may have a variant located elsewhere in the block data
+ *     getVariant: (props) => props.item?.link?.variant,
+ *     variants: {
+ *       reversed: (props) => <BlockButtons theme="reversed" {...props} />,
+ *       primary: (props) => <BlockButtons tokens={{ buttonStyle: 'primary' }} {...props} />,
+ *     },
+ *   },
+ * }
+ * ```
+ */
+export type TBlockSerializerConfigComponent<Fragment extends TCommonBlockFragment = TCommonBlockFragment, Variables extends GraphQLVariables = TBlockVariables, AdditionalProps extends TAdditionalProps = TAdditionalProps> = {
     [blockKey: string]: {
-        default: TBlockFunctionComponent<BlockFragment>;
-        document?: TBlockDocument<BlockFragment>;
+        default: TBlockFunctionComponent<Fragment, Variables, AdditionalProps>;
+        /**
+         * The necessary GraphQL document for querying the data. This prop can either be passed directly to the block or in the config.
+         */
+        document?: TBlockDocument<Fragment, Variables>;
+        /**
+         * @default 'default'
+         */
         defaultVariant?: string;
-        getVariant?: (props: TBlockSerializerProps<BlockFragment>) => Nullable<string>;
+        /**
+         * A callback to specify a different variant path from the one in the block's settings.
+         */
+        getVariant?: (props: TBlockSerializerProps<Fragment, Variables, AdditionalProps>) => Nullable<string>;
         variants?: {
-            [blockVariant: string]: TBlockFunctionComponent<BlockFragment>;
+            [blockVariant: string]: TBlockFunctionComponent<Fragment, Variables, AdditionalProps>;
         };
     };
 };
+/**
+ * A configuration for the block serializer. Usually, it's a bad idea to define the config components directly in the main config since each config component needs its own type parameters.
+ */
 export interface TBlockSerializerConfig {
     components: TBlockSerializerConfigComponent;
 }

package/hooks/useBlock.d.ts

@@ -1,8 +1,23 @@
 import type { TToken } from '@okam/stack-ui';
-import type { TypedQueryDocumentNode } from 'graphql';
 import type { TBlockSerializerProps } from '../components/BlockSerializer/interface';
-import type { TBlockQuery, TBlockVariables, TCommonBlockFragment } from '../types/block';
-declare function useBlock<T extends TCommonBlockFragment>(props: TBlockSerializerProps<T>, blockKey: string, doc?: TypedQueryDocumentNode<TBlockQuery<T>, TBlockVariables>): Promise<T & {
+import type { TBlockDocument, TBlockVariables, TCommonBlockFragment } from '../types/block';
+/**
+ * General function to fetch the block data and its settings. Features the decision-making logic of {@link getBlockProps} that allows blocks to work with both passed props and queried props.
+ * @param props Props of the block component. Pass props directly from the block component.
+ * @param blockKey Key of the block data in the GraphQL document. Allows mapping props regardless of the block's collection name. Usually the block's collection name with `_by_id` appended since most queries are made by id.
+ * @param doc Alternative for passing the GraphQL document to the block component. If not passed, the document will be retrieved from the block's props or config.
+ * @returns The block data and its settings.
+ *
+ * @example
+ * ```tsx
+ * const BlockButtons = (props: TBlockSerializerProps<BlockButtonsFragment>) => {
+ *   const key = 'block_buttons_by_id'
+ *   const { tokens } = props
+ *   const { link, cmsTokens, variant } = await useBlock(props, key)
+ *   return <Link {...link} tokens={{ ...tokens, ...cmsTokens, style: variant }} />
+ * }
+ * ```
+ */
+export default function useBlock<Fragment extends TCommonBlockFragment, Variables extends TBlockVariables = TBlockVariables>(props: TBlockSerializerProps<Fragment, Variables>, blockKey: string, doc?: TBlockDocument<Fragment, Variables>): Promise<Fragment & {
     cmsTokens: TToken;
 }>;
-export default useBlock;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@okam/directus-block",
-  "version": "1.5.21",
+  "version": "1.6.0",
   "main": "./index.js",
   "types": "./index.d.ts",
   "exports": {
@@ -34,7 +34,7 @@
   "dependencies": {
     "@graphql-typed-document-node/core": "3.2.0",
     "@okam/directus-query": "1.4.2",
-    "@okam/stack-ui": "1.42.2",
+    "@okam/stack-ui": "1.42.3",
     "graphql": "^16.9.0",
     "graphql-request": "^7.1.2",
     "radashi": "^12.3.0",