Add pickers for rule creation with control API and CLI examples

src/components/Layout/MDXWrapper.tsx

@@ -22,6 +22,7 @@ import { Tiles } from './mdx/tiles';
 import { PageHeader } from './mdx/PageHeader';
 import Admonition from './mdx/Admonition';
 import { MethodSignature } from './mdx/MethodSignature';
+import { MethodPicker, Method } from './mdx/MethodPicker';
 
 import { Frontmatter, PageContextType } from './Layout';
 import { ActivePage } from './utils/nav';
@@ -339,6 +340,8 @@ const MDXWrapper: React.FC<MDXWrapperProps> = ({ children, pageContext, location
               td: Table.Cell,
               Tiles,
               MethodSignature,
+              MethodPicker,
+              Method,
             }}
           >
             <PageHeader title={title} intro={intro} />

src/components/Layout/mdx/MethodPicker.tsx

@@ -0,0 +1,67 @@
+import React, { useState, createContext, useContext, isValidElement, ReactNode } from 'react';
+import cn from '@ably/ui/core/utils/cn';
+
+type MethodContextType = {
+  activeMethod: string;
+};
+
+const MethodContext = createContext<MethodContextType | undefined>(undefined);
+
+const METHOD_LABELS: Record<string, string> = {
+  dashboard: 'Dashboard',
+  'control-api': 'Control API',
+  cli: 'Ably CLI',
+};
+
+interface MethodProps {
+  value: string;
+  children: ReactNode;
+}
+
+export const Method: React.FC<MethodProps> = ({ value, children }) => {
+  const context = useContext(MethodContext);
+  if (!context) {
+    return null;
+  }
+  return context.activeMethod === value ? <>{children}</> : null;
+};
+
+interface MethodPickerProps {
+  children: ReactNode;
+}
+
+export const MethodPicker: React.FC<MethodPickerProps> = ({ children }) => {
+  // Extract method values from Method children
+  const methods: string[] = [];
+  React.Children.forEach(children, (child) => {
+    if (isValidElement<MethodProps>(child) && child.props.value) {
+      methods.push(child.props.value);
+    }
+  });
+
+  const [activeMethod, setActiveMethod] = useState(methods[0] ?? 'dashboard');
+
+  return (
+    <MethodContext.Provider value={{ activeMethod }}>
+      <div className="my-5">
+        <div className="flex gap-1 border-b border-neutral-300 dark:border-neutral-800 mb-5">
+          {methods.map((method) => (
+            <button
+              key={method}
+              onClick={() => setActiveMethod(method)}
+              className={cn(
+                'px-4 py-2 text-sm font-medium rounded-t-md transition-colors cursor-pointer',
+                activeMethod === method
+                  ? 'bg-neutral-100 dark:bg-neutral-1100 text-neutral-1300 dark:text-neutral-000 border border-neutral-300 dark:border-neutral-800 border-b-transparent -mb-px'
+                  : 'text-neutral-700 dark:text-neutral-500 hover:text-neutral-1000 dark:hover:text-neutral-300',
+              )}
+            >
+              {METHOD_LABELS[method] ?? method}
+            </button>
+          ))}
+        </div>
+        <div>{children}</div>
+      </div>
+    </MethodContext.Provider>
+  );
+};

src/pages/docs/channels/index.mdx

@@ -202,7 +202,10 @@ The rules related to enabling features are:
 | Message conflation | If enabled, messages are aggregated over a set period of time and evaluated against a conflation key. All but the latest message for each conflation key value will be discarded, and the resulting message, or messages, will be delivered to subscribers as a single batch once the period of time elapses. [Message conflation](/docs/messages#conflation) reduces costs in high-throughput scenarios by removing redundant and outdated messages. |
 | Message annotations, updates, deletes, and appends | If enabled, allows message "annotations":/docs/messages/annotations to be used, as well as updates, deletes, and appends to be published to messages. Note that these features are currently in public preview. When this feature is enabled, messages will be "persisted":/docs/storage-history/storage#all-message-persistence (necessary in order from them later be annotated or updated), and "continuous history":/docs/storage-history/history#continuous-history features will not work.
 
-To set a rule in the Ably dashboard:
+To set a rule:
+
+<MethodPicker>
+<Method value="dashboard">
 
 1. Sign in to your Ably account.
 2. Select an app.
@@ -211,6 +214,47 @@ To set a rule in the Ably dashboard:
 5. Select channel name or namespace to apply rules to.
 6. Check required rules.
 
+</Method>
+<Method value="control-api">
+
+Use the [Control API](/docs/platform/account/control-api) to create a channel rule by sending a `POST` request to `/apps/{app_id}/namespaces`:
+
+<Code>
+```shell
+curl -X POST https://control.ably.net/v1/apps/{APP_ID}/namespaces \
+  -H "Authorization: Bearer {ACCESS_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "id": "my-namespace",
+    "persisted": true,
+    "persistLast": false,
+    "pushEnabled": false,
+    "tlsOnly": false,
+    "authenticated": false
+  }'
+```
+</Code>
+
+Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters.
+
+</Method>
+<Method value="cli">
+
+Use the [Ably CLI](/docs/platform/tools/cli) to create a channel rule:
+
+<Code>
+```shell
+ably apps rules create \
+  --name "my-namespace" \
+  --persisted
+```
+</Code>
+
+Run `ably apps rules create --help` for a full list of available options.
+
+</Method>
+</MethodPicker>
+
 ## Channel history <a id="history"/>
 
 Channel [history](/docs/storage-history/history) enables clients to retrieve messages that have been previously published on the channel. Messages can be retrieved from history for up to 72 hours in the past, depending on the [persistence](/docs/storage-history/storage) configured for the channel.

src/pages/docs/livesync/mongodb/index.mdx

@@ -24,17 +24,46 @@ When a change event is received over the Change Streams API it is published to a
 
 You first need to create an integration rule in order to sync your MongoDB instance with Ably.
 
-There are two ways to create a MongoDB database connector rule:
-
-1. Using the [Ably Dashboard](https://ably.com/dashboard).
-2. Using the [Control API](/docs/platform/account/control-api).
+<MethodPicker>
+<Method value="dashboard">
 
 To create a rule in your [dashboard](https://ably.com/dashboard):
 
 1. Log in and select the application you wish to use.
-2. Click the *Integrations* tab.
-3. Click the *New Integration Rule* button.
-4. Choose *MongoDB* from the list.
+2. Click the **Integrations** tab.
+3. Click the **New Integration Rule** button.
+4. Choose **MongoDB** from the list.
+5. Configure the [rule settings](#config).
+
+</Method>
+<Method value="control-api">
+
+Use the [Control API](/docs/platform/account/control-api) to create a MongoDB rule by sending a `POST` request to `/apps/{app_id}/rules`:
+
+<Code>
+```shell
+curl -X POST https://control.ably.net/v1/apps/{APP_ID}/rules \
+  -H "Authorization: Bearer {ACCESS_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "ruleType": "ingress/mongodb",
+    "target": {
+      "url": "mongodb://user:pass@myhost.com",
+      "database": "my-database",
+      "collection": "my-collection",
+      "pipeline": "[{\"$set\": {\"_ablyChannel\": \"myDocuments\"}}]",
+      "fullDocument": "off",
+      "fullDocumentBeforeChange": "off",
+      "primarySite": "us-east-1-A"
+    }
+  }'
+```
+</Code>
+
+Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters.
+
+</Method>
+</MethodPicker>
 
 ### Rule configuration <a id="config"/>
 

src/pages/docs/livesync/postgres/index.mdx

@@ -34,15 +34,46 @@ By writing change events to the outbox table within the same database transactio
 
 ### Creating the rule <a id="create"/>
 
-There are two ways to create a Postgres integration rule:
-1. Using the [Ably Dashboard](https://ably.com/dashboard).
-2. Using the [Control API](/docs/platform/account/control-api).
+<MethodPicker>
+<Method value="dashboard">
 
 To create a rule in your [dashboard](https://ably.com/dashboard):
+
 1. Login and select the application you wish to use.
-2. Click the *Integrations* tab.
-3. Click the *New Integration Rule* button.
-4. Choose *Postgres* from the list.
+2. Click the **Integrations** tab.
+3. Click the **New Integration Rule** button.
+4. Choose **Postgres** from the list.
+5. Configure the [rule settings](#configure).
+
+</Method>
+<Method value="control-api">
+
+Use the [Control API](/docs/platform/account/control-api) to create a Postgres rule by sending a `POST` request to `/apps/{app_id}/rules`:
+
+<Code>
+```shell
+curl -X POST https://control.ably.net/v1/apps/{APP_ID}/rules \
+  -H "Authorization: Bearer {ACCESS_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "ruleType": "ingress-postgres-outbox",
+    "target": {
+      "url": "postgres://user:password@example.com:5432/your-database-name",
+      "outboxTableSchema": "public",
+      "outboxTableName": "outbox",
+      "nodesTableSchema": "public",
+      "nodesTableName": "nodes",
+      "sslMode": "prefer",
+      "primarySite": "us-east-1-A"
+    }
+  }'
+```
+</Code>
+
+Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters.
+
+</Method>
+</MethodPicker>
 
 ### Rule configuration <a id="configure"/>
 

src/pages/docs/messages/annotations.mdx

@@ -27,11 +27,51 @@ When message annotations are enabled, messages are [persisted](/docs/storage-his
 [Continuous history](/docs/storage-history/history#continuous-history) features are not supported. Be aware that if you are currently using continuous history and enable annotations, updates, deletes, and appends, continuous history will no longer function.
 </Aside>
 
+<MethodPicker>
+<Method value="dashboard">
+
 1. Go to the **Settings** tab of an app in your dashboard.
-3. Under [rules](/docs/channels#rules), click **Add new rule**.
-4. Enter the channel name or channel namespace on which to enable message annotations.
-5. Check **Message annotations, updates, deletes, and appends** to enable message annotations.
-6. Click **Create rule** to save.
+2. Under [rules](/docs/channels#rules), click **Add new rule**.
+3. Enter the channel name or channel namespace on which to enable message annotations.
+4. Check **Message annotations, updates, deletes, and appends** to enable message annotations.
+5. Click **Create rule** to save.
+
+</Method>
+<Method value="control-api">
+
+Use the [Control API](/docs/platform/account/control-api) to create a channel rule with annotations enabled by sending a `POST` request to `/apps/{app_id}/namespaces`:
+
+<Code>
+```shell
+curl -X POST https://control.ably.net/v1/apps/{APP_ID}/namespaces \
+  -H "Authorization: Bearer {ACCESS_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "id": "my-namespace",
+    "mutableMessages": true
+  }'
+```
+</Code>
+
+Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters.
+
+</Method>
+<Method value="cli">
+
+Use the [Ably CLI](/docs/platform/tools/cli) to create a channel rule with annotations enabled:
+
+<Code>
+```shell
+ably apps rules create \
+  --name "my-namespace" \
+  --mutable-messages
+```
+</Code>
+
+Run `ably apps rules create --help` for a full list of available options.
+
+</Method>
+</MethodPicker>
 
 ## Annotation types <a id="annotation-types"/>
 

src/pages/docs/messages/batch.mdx

@@ -27,16 +27,58 @@ When configuring server-side batching, you need to configure a batching interval
 
 Each batch can contain up to 200 messages by count or total data size. For example, if you have 210 messages, they will be split into two batches: one with 200 messages and another with 10 messages. If the combined data size of 200 messages exceeds the data limit, the excess will be allocated to a new batch as separate messages.
 
-Use the following steps to configure server-side batching for a channel, or channel namespace:
+Use one of the following methods to configure server-side batching for a channel or channel namespace:
+
+<MethodPicker>
+<Method value="dashboard">
 
 1. On your [dashboard](https://ably.com/accounts/any), select one of your apps.
 2. Go to **Settings**.
 3. Under [rules](/docs/channels#rules), click **Add new rule**.
-4. Enter the channel name, or channel namespace to apply server-side batching to.
+4. Enter the channel name or channel namespace to apply server-side batching to.
 5. Check **Server-side batching enabled**.
 6. Choose a batching interval over which to aggregate messages.
 7. Click **Create rule** to save.
 
+</Method>
+<Method value="control-api">
+
+Use the [Control API](/docs/platform/account/control-api) to create a channel rule with server-side batching by sending a `POST` request to `/apps/{app_id}/namespaces`:
+
+<Code>
+```shell
+curl -X POST https://control.ably.net/v1/apps/{APP_ID}/namespaces \
+  -H "Authorization: Bearer {ACCESS_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "id": "my-namespace",
+    "batchingEnabled": true,
+    "batchingInterval": 100
+  }'
+```
+</Code>
+
+Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters.
+
+</Method>
+<Method value="cli">
+
+Use the [Ably CLI](/docs/platform/tools/cli) to create a channel rule with server-side batching:
+
+<Code>
+```shell
+ably apps rules create \
+  --name "my-namespace" \
+  --batching-enabled \
+  --batching-interval 100
+```
+</Code>
+
+Run `ably apps rules create --help` for a full list of available options.
+
+</Method>
+</MethodPicker>
+
 <Aside data-type="note">
 Server side batching is mutually exclusive with [message conflation](/docs/messages#conflation) on a channel, or channel namespace.
 </Aside>