@tridion-sites/extensions 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,155 @@
+# Tridion Sites Extensions API
+
+`@tridion-sites/extensions` provides an API for frontend extensions for Tridion Sites.
+
+## Getting Started
+
+All extensions export an [`ExtensionModule`](https://developers.rws.com/tridion-sites-extensions-api-docs/extensions.extensionmodule.html) object. The `initialize` function on this object receives an [`ExtensionBuilder`](https://developers.rws.com/tridion-sites-extensions-api-docs/extensions.extensionbuilder.html) from Tridion Sites as its argument, which gives a developer access to the extensions API.
+
+## Common functionality
+
+This functionality can be used in any extension point and is available throughout the application.
+
+### Hooks
+
+| Name                                                                                                               | Description                                                            | Example                                                                                                                                                                       |
+| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [useConfirmation](https://developers.rws.com/tridion-sites-extensions-api-docs/extensions.confirmationhook.html)   | Allows to add a confirmation dialog to an operation                    | [Hello action](https://github.com/RWS/tridion-sites-extensions-examples/blob/main/activities-explorer/simple-action-addon/hello-action/src/helloAction/useHelloAction.ts#L24) |
+| [useNotifications](https://developers.rws.com/tridion-sites-extensions-api-docs/extensions.notificationshook.html) | Provides ability to show notifications and save them in Message Center | [Hello action](https://github.com/RWS/tridion-sites-extensions-examples/blob/main/activities-explorer/simple-action-addon/hello-action/src/helloAction/useHelloAction.ts#L16) |
+| [useUserProfile](https://developers.rws.com/tridion-sites-extensions-api-docs/extensions.userprofilehook.html)     | Provides access to the current user profile information                | [Hello action](https://github.com/RWS/tridion-sites-extensions-examples/blob/main/activities-explorer/simple-action-addon/hello-action/src/helloAction/useHelloAction.ts#L12) |
+
+### Components and styling
+
+Components and style constants are provided so extensions can maintain a consistent look & feel with Tridion Sites.
+
+#### Layout
+
+| Name       | Description | Example |
+| ---------- | ----------- | ------- |
+| [Block]()  |             |         |
+| [Center]() |             |         |
+| [Flex]()   |             |         |
+| [Stack]()  |             |         |
+
+#### Other components
+
+| Name         | Description | Example |
+| ------------ | ----------- | ------- |
+| [Button]()   |             |         |
+| [Icon]()     |             |         |
+| [Link]()     |             |         |
+| [Text]()     |             |         |
+| [TextLink]() |             |         |
+
+#### Style constants
+
+| Name                      | Description | Example |
+| ------------------------- | ----------- | ------- |
+| [getBorderRadius]()       |             |         |
+| [getColorPalette]()       |             |         |
+| [getOpacityLevel]()       |             |         |
+| [getSpacing]()            |             |         |
+| [getTransitionDuration]() |             |         |
+| [getZIndex]()             |             |         |
+
+## Data loading
+
+Mutations and queries provide a way to requires Tridion Sites data. They operate with model instances of [`@tridion-sites/models`](https://www.npmjs.com/package/@tridion-sites/models) package rather than simple objects of [`@tridion-sites/open-api-client`](https://www.npmjs.com/package/@tridion-sites/open-api-client).
+
+_💡 **Tip:** Mutations and queries share cached data between the host application and extensions. This means that if provided request was already loaded somewhere else - it is going to be retrieved from the cache if applicable._
+
+### Queries
+
+Queries provide a way of retrieving data from the backend as well as managing its loading and reloading.
+
+| Name                                      | Description | Example |
+| ----------------------------------------- | ----------- | ------- |
+| [useActivityInstancesQuery]()             |             |         |
+| [useDefaultTranslationJobQuery]()         |             |         |
+| [useFavoritesQuery]()                     |             |         |
+| [useItemBlueprintHierarchyQuery]()        |             |         |
+| [useItemChildrenQuery]()                  |             |         |
+| [useItemClassifiedItemsQuery]()           |             |         |
+| [useItemDefaultDataQuery]()               |             |         |
+| [useItemHistoryQuery]()                   |             |         |
+| [useItemPublishedPagesQuery]()            |             |         |
+| [useItemPublishedToQuery]()               |             |         |
+| [useItemPublishUrlsQuery]()               |             |         |
+| [useItemQuery]()                          |             |         |
+| [useItemsInProgressQuery]()               |             |         |
+| [useItemsQuery]()                         |             |         |
+| [useItemsToPublishQuery]()                |             |         |
+| [useItemsToUnpublishQuery]()              |             |         |
+| [useItemTranslationInfoQuery]()           |             |         |
+| [useItemUsedByQuery]()                    |             |         |
+| [useItemUsesQuery]()                      |             |         |
+| [usePublicationBlueprintHierarchyQuery]() |             |         |
+| [usePublicationsQuery]()                  |             |         |
+| [usePublishableTargetTypesQuery]()        |             |         |
+| [useSearchInContainerQuery]()             |             |         |
+| [useSystemSearchQuery]()                  |             |         |
+| [useUserGroupsQuery]()                    |             |         |
+| [useUserProfileQuery]()                   |             |         |
+| [useUsersQuery]()                         |             |         |
+
+### Mutations
+
+Mutations provide a way of changing data on the backend as well as handling request execution.
+
+| Name                                | Description | Example |
+| ----------------------------------- | ----------- | ------- |
+| [useAddToBundleMutation]()          |             |         |
+| [useAssignActivitiesMutation]()     |             |         |
+| [useAssignActivityMutation]()       |             |         |
+| [useAutoClassifyItemMutation]()     |             |         |
+| [useAutoClassifyItemsMutation]()    |             |         |
+| [useChangeUserLanguageMutation]()   |             |         |
+| [useChangeUserLocaleMutation]()     |             |         |
+| [useCopyItemMutation]()             |             |         |
+| [useCopyItemsMutation]()            |             |         |
+| [useCreateTranslationJobMutation]() |             |         |
+| [useDeleteItemMutation]()           |             |         |
+| [useDeleteItemsMutation]()          |             |         |
+| [useFinishActivitiesMutation]()     |             |         |
+| [useFinishActivityMutation]()       |             |         |
+| [useFinishEditingItemMutation]()    |             |         |
+| [useFinishEditingItemsMutation]()   |             |         |
+| [useLocalizeItemMutation]()         |             |         |
+| [useLocalizeItemsMutation]()        |             |         |
+| [useMoveItemMutation]()             |             |         |
+| [useMoveItemsMutation]()            |             |         |
+| [usePublishItemsMutation]()         |             |         |
+| [useRemoveFromBundleMutation]()     |             |         |
+| [useRestartActivitiesMutation]()    |             |         |
+| [useRestartActivityMutation]()      |             |         |
+| [useRevertItemMutation]()           |             |         |
+| [useRevertItemsMutation]()          |             |         |
+| [useRollbackItemMutation]()         |             |         |
+| [useStartActivitiesMutation]()      |             |         |
+| [useStartActivityMutation]()        |             |         |
+| [useStartWorkflowMutation]()        |             |         |
+| [useUnlocalizeItemMutation]()       |             |         |
+| [useUnlocalizeItemsMutation]()      |             |         |
+| [useUnpublishItemsMutation]()       |             |         |
+| [useUpdateItemMutation]()           |             |         |
+| [useUploadMultimediaMutation]()     |             |         |
+
+## Data Contexts
+
+Tridion Sites contains nested data contexts. All extension points and hooks exist within a data context. Within any given data context, one can access both the data in that context and any parent data contexts. It is important to note where an extension is located to determine what data it can access.
+
+_💡 **Tip:** Some extensions might appear in multiple places. Hooks with optional contexts are provided for this purpose._
+
+-   Activities Explorer
+    -   Activities Explorer Table
+-   Content Explorer
+    -   Content Explorer Table
+    -   Content Explorer Tree
+-   Content editors
+    -   Bundle editor
+    -   Category editor
+    -   Component editor
+    -   Folder editor
+    -   Keyword editor
+    -   Page editor
+    -   Structure group editor

package/dist/index.d.ts

@@ -348,7 +348,7 @@ export declare type AddToBundleMutationHook = (options?: MutationOptions<Mutatio
 export declare interface AddToBundleRequest {
     bundleId: ItemUri;
     itemsToAdd: ReadonlyArray<IdentifiableObject>;
-    contextItem?: IdentifiableObject;
+    containerItem?: IdentifiableObject;
 }
 
 /**
@@ -436,7 +436,7 @@ export declare type AutoClassifyItemMutationHook = (options?: MutationOptions<Cl
  */
 export declare interface AutoClassifyItemRequest {
     itemId: ItemUri;
-    contextItem?: IdentifiableObject;
+    containerItem?: IdentifiableObject;
 }
 
 /**
@@ -477,7 +477,7 @@ declare type BatchMutationOptions<TVariables> = MutationOptions<Batch, ApiError,
  * including the className and cssStyle props for custom styling.
  *
  * It should rarely be used directly as preference should be given to the more specialized child components.
- * @internal
+ * @public
  */
 export declare const Block: BlockComponent;
 
@@ -571,7 +571,7 @@ export declare interface BundleEditorHooksApiStorage {
 
 /**
  * A component that has standard button functionality.
- * @internal
+ * @public
  */
 export declare const Button: ButtonComponent;
 
@@ -640,7 +640,7 @@ export declare interface CategoryEditorHooksApiStorage {
  *
  * It is advisable to construct most of the layout using this component as it allows to freely utilize
  * "shouldFill" and similar props that rely on the parent being a Flex component.
- * @internal
+ * @public
  */
 export declare const Center: CenterComponent;
 
@@ -1321,7 +1321,7 @@ export declare type DeleteItemMutationHook = (options?: MutationOptions<void, Ap
  */
 export declare interface DeleteItemRequest {
     item: IdentifiableObject;
-    contextItem?: IdentifiableObject;
+    containerItem?: IdentifiableObject;
 }
 
 /**
@@ -1498,7 +1498,7 @@ export declare type FinishEditingItemMutationHook = (options?: MutationOptions<R
  */
 export declare interface FinishEditingItemRequest {
     item: VersionedItem;
-    contextItem?: IdentifiableObject;
+    containerItem?: IdentifiableObject;
 }
 
 /**
@@ -1520,7 +1520,7 @@ export declare interface FinishItemsRequest {
  *
  * It is advisable to construct most of the layout using this component as it allows to freely utilize
  * "shouldFill" and similar props that rely on the parent being a Flex component.
- * @internal
+ * @public
  */
 export declare const Flex: FlexComponent;
 
@@ -1755,7 +1755,7 @@ export declare type GetBorderRadius = () => BorderRadius;
 
 /**
  * System-predefined border radiuses.
- * @internal
+ * @public
  */
 export declare const getBorderRadius: GetBorderRadius;
 
@@ -1766,7 +1766,7 @@ export declare type GetColorPalette = () => ColorPalette;
 
 /**
  * System-predefined color palette.
- * @internal
+ * @public
  */
 export declare const getColorPalette: GetColorPalette;
 
@@ -1779,7 +1779,7 @@ export declare type GetOpacityLevel = () => OpacityLevel;
 
 /**
  * System-predefined opacity levels.
- * @internal
+ * @public
  */
 export declare const getOpacityLevel: GetOpacityLevel;
 
@@ -1790,7 +1790,7 @@ export declare type GetSpacing = () => Spacing;
 
 /**
  * System-predefined spacings.
- * @internal
+ * @public
  */
 export declare const getSpacing: GetSpacing;
 
@@ -1801,7 +1801,7 @@ export declare type GetTransitionDuration = () => TransitionDuration;
 
 /**
  * System-predefined transition duration.
- * @internal
+ * @public
  */
 export declare const getTransitionDuration: GetTransitionDuration;
 
@@ -1812,7 +1812,7 @@ export declare type GetZIndex = () => ZIndex;
 
 /**
  * System-predefined z-index values.
- * @internal
+ * @public
  */
 export declare const getZIndex: GetZIndex;
 
@@ -1833,7 +1833,7 @@ export declare class HeaderExtensionsBuilder {
 
 /**
  * A component used for rendering SVG icons.
- * @internal
+ * @public
  */
 export declare const Icon: IconComponent;
 
@@ -2156,7 +2156,7 @@ export declare type LanguageCode = 'de' | 'en' | 'es' | 'fr' | 'nl' | 'zh' | 'ja
 
 /**
  * A component to wrap any custom view with Link for navigation
- * @internal
+ * @public
  */
 export declare const Link: LinkComponent;
 
@@ -2215,7 +2215,7 @@ export declare type LocalizeItemMutationHook = (options?: MutationOptions<Reposi
  */
 export declare interface LocalizeItemRequest {
     itemId: ItemUri;
-    contextItem?: IdentifiableObject;
+    containerItem?: IdentifiableObject;
 }
 
 /**
@@ -2387,10 +2387,6 @@ export declare type NavigationItemHook = () => {
      * If `true`, navigation menu item and its corresponding page are available.
      */
     readonly isAvailable: boolean;
-    /**
-     * If `true`, navigation item has enough information to determine its availability.
-     */
-    readonly isInitialized: boolean;
     /**
      * Navigation item label.
      */
@@ -2918,7 +2914,7 @@ export declare type RevertItemMutationHook = (options?: MutationOptions<Reposito
  */
 export declare interface RevertItemRequest {
     item: IdentifiableObject;
-    contextItem?: IdentifiableObject;
+    containerItem?: IdentifiableObject;
 }
 
 /**
@@ -3022,7 +3018,7 @@ export declare type RollbackItemMutationHook = (options?: MutationOptions<Reposi
  */
 export declare interface RollbackItemRequest {
     itemId: ItemUri;
-    contextItem?: IdentifiableObject;
+    containerItem?: IdentifiableObject;
     deleteNewerVersions: boolean;
 }
 
@@ -3175,7 +3171,7 @@ declare type SpacingUnit_2 = keyof typeof spacing;
  *
  * Items can't have size that depends on Stack's size. This means that it is impossible to make item take available space or
  * have size in percentage of Stack's size.
- * @internal
+ * @public
  */
 export declare const Stack: StackComponent;
 
@@ -3412,7 +3408,7 @@ export declare type TextDirection = 'leftToRight' | 'rightToLeft';
 
 /**
  * A component to render Text Link for navigation
- * @internal
+ * @public
  */
 export declare const TextLink: TextLinkComponent;
 
@@ -3535,7 +3531,7 @@ export declare type UnlocalizeItemMutationHook = (options?: MutationOptions<Repo
  */
 export declare interface UnlocalizeItemRequest {
     itemId: ItemUri;
-    contextItem?: IdentifiableObject;
+    containerItem?: IdentifiableObject;
     useDynamicVersion?: boolean;
 }
 

package/dist/index.js

@@ -1122,7 +1122,7 @@ const useOptionalStructureGroupEditor = () => {
  * including the className and cssStyle props for custom styling.
  *
  * It should rarely be used directly as preference should be given to the more specialized child components.
- * @internal
+ * @public
  */
 const Block = memo(props => {
     const Block = extensionApiBridge.get().general.components.Block;
@@ -1131,7 +1131,7 @@ const Block = memo(props => {
 Block.displayName = 'Block';
 /**
  * A component that has standard button functionality.
- * @internal
+ * @public
  */
 const Button = memo(props => {
     const Button = extensionApiBridge.get().general.components.Button;
@@ -1145,7 +1145,7 @@ Button.displayName = 'Button';
  *
  * It is advisable to construct most of the layout using this component as it allows to freely utilize
  * "shouldFill" and similar props that rely on the parent being a Flex component.
- * @internal
+ * @public
  */
 const Center = memo(props => {
     const Center = extensionApiBridge.get().general.components.Center;
@@ -1158,7 +1158,7 @@ Center.displayName = 'Center';
  *
  * It is advisable to construct most of the layout using this component as it allows to freely utilize
  * "shouldFill" and similar props that rely on the parent being a Flex component.
- * @internal
+ * @public
  */
 const Flex = memo(props => {
     const Flex = extensionApiBridge.get().general.components.Flex;
@@ -1167,7 +1167,7 @@ const Flex = memo(props => {
 Flex.displayName = 'Flex';
 /**
  * A component used for rendering SVG icons.
- * @internal
+ * @public
  */
 const Icon = memo(props => {
     const Icon = extensionApiBridge.get().general.components.Icon;
@@ -1176,7 +1176,7 @@ const Icon = memo(props => {
 Icon.displayName = 'Icon';
 /**
  * A component to wrap any custom view with Link for navigation
- * @internal
+ * @public
  */
 const Link = memo(props => {
     const Link = extensionApiBridge.get().general.components.Link;
@@ -1188,7 +1188,7 @@ Link.displayName = 'Link';
  *
  * Items can't have size that depends on Stack's size. This means that it is impossible to make item take available space or
  * have size in percentage of Stack's size.
- * @internal
+ * @public
  */
 const Stack = memo(props => {
     const Stack = extensionApiBridge.get().general.components.Stack;
@@ -1205,7 +1205,7 @@ const Text = memo(props => {
 Text.displayName = 'Text';
 /**
  * A component to render Text Link for navigation
- * @internal
+ * @public
  */
 const TextLink = memo(props => {
     const TextLink = extensionApiBridge.get().general.components.TextLink;
@@ -1215,32 +1215,32 @@ TextLink.displayName = 'TextLink';
 
 /**
  * System-predefined border radiuses.
- * @internal
+ * @public
  */
 const getBorderRadius = () => extensionApiBridge.get().general.globals.getBorderRadius();
 /**
  * System-predefined color palette.
- * @internal
+ * @public
  */
 const getColorPalette = () => extensionApiBridge.get().general.globals.getColorPalette();
 /**
  * System-predefined opacity levels.
- * @internal
+ * @public
  */
 const getOpacityLevel = () => extensionApiBridge.get().general.globals.getOpacityLevel();
 /**
  * System-predefined spacings.
- * @internal
+ * @public
  */
 const getSpacing = () => extensionApiBridge.get().general.globals.getSpacing();
 /**
  * System-predefined transition duration.
- * @internal
+ * @public
  */
 const getTransitionDuration = () => extensionApiBridge.get().general.globals.getTransitionDuration();
 /**
  * System-predefined z-index values.
- * @internal
+ * @public
  */
 const getZIndex = () => extensionApiBridge.get().general.globals.getZIndex();
 
@@ -1729,7 +1729,7 @@ const createExtensionGlobals = () => {
     };
 };
 
-const version = "1.0.0";
+const version = "1.0.2";
 const peerDependencies = {
 	"@tridion-sites/models": "workspace:*",
 	"@tridion-sites/open-api-client": "workspace:*",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tridion-sites/extensions",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Tridion Sites Extensions API",
   "author": "RWS",
   "homepage": "https://www.rws.com",