@dxos/plugin-observability 0.8.4-main.406dc2a → 0.8.4-main.4a85c3132b

package/src/components/FeedbackForm.stories.tsx

@@ -0,0 +1,33 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '../translations';
+
+import { FeedbackForm } from './FeedbackForm';
+
+const meta = {
+  title: 'plugins/plugin-observability/components/FeedbackForm',
+  component: FeedbackForm,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof FeedbackForm>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    onSave: (values) => {
+      console.log(values);
+    },
+  },
+};

package/src/components/FeedbackForm.tsx

@@ -2,81 +2,32 @@
 // Copyright 2024 DXOS.org
 //
 
-import React, { useCallback, useRef, useState } from 'react';
+import React from 'react';
 
-import { getSnapshot } from '@dxos/echo/internal';
-import { IconButton, Input, useTranslation } from '@dxos/react-ui';
-import { FormProvider, useFormContext, useInputProps } from '@dxos/react-ui-form';
+import { useTranslation } from '@dxos/react-ui';
+import { Form, type FormRootProps, type FormSubmitProps } from '@dxos/react-ui-form';
 
 import { meta } from '../meta';
 import { UserFeedback } from '../types';
 
-const defaultValues: UserFeedback = { message: '' };
+export type FeedbackFormProps = Pick<FormRootProps<UserFeedback>, 'onSave'> & Pick<FormSubmitProps, 'disabled'>;
 
-const FormContent = () => {
-  const { t } = useTranslation(meta.id);
-  const { handleSave, canSave } = useFormContext<UserFeedback>();
-
-  const messageProps = useInputProps(['message']);
-
-  return (
-    <div role='form' className='p-3 flex flex-col gap-2'>
-      <div role='none' className='space-b-1'>
-        <Input.Root validationValence={messageProps.getStatus().status}>
-          <Input.Label>{t('feedback text area label')}</Input.Label>
-          <Input.TextArea
-            classNames={'text-sm'}
-            rows={5}
-            cols={30}
-            placeholder={t('feedback text area placeholder')}
-            value={messageProps.getValue() ?? ''}
-            onChange={(e) => messageProps.onValueChange('string', e.target.value)}
-            // TODO(wittjosiah): This aggressively shows validation errors.
-            onBlur={messageProps.onBlur}
-          />
-          <Input.DescriptionAndValidation>
-            <Input.Validation>{messageProps.getStatus().error}</Input.Validation>
-          </Input.DescriptionAndValidation>
-        </Input.Root>
-      </div>
-
-      <div role='none' className='space-b-2'>
-        <IconButton
-          icon='ph--paper-plane-tilt--regular'
-          label={t('send feedback label')}
-          variant='primary'
-          type='submit'
-          classNames='is-full'
-          disabled={!canSave}
-          onClick={handleSave}
-        />
-      </div>
-    </div>
-  );
+const defaultValues: UserFeedback = {
+  message: '',
+  includeLogs: true,
 };
 
-// TODO(wittjosiah): Use `Form`?
-export const FeedbackForm = ({ onSave }: { onSave: (values: UserFeedback) => void }) => {
-  const formRef = useRef<HTMLDivElement>(null);
-  const [_, update] = useState({});
-  const forceRender = useCallback(() => update({}), [update]);
-
-  const handleSave = useCallback(
-    (values: UserFeedback) => {
-      onSave(values);
-      // TODO(wittjosiah): Force re-render to clear the form.
-      forceRender();
-    },
-    [forceRender, onSave],
-  );
-
-  const initialValues = getSnapshot(defaultValues);
+export const FeedbackForm = ({ onSave, disabled }: FeedbackFormProps) => {
+  const { t } = useTranslation(meta.id);
 
   return (
-    <FormProvider formRef={formRef} schema={UserFeedback} initialValues={initialValues} onSave={handleSave}>
-      <div ref={formRef}>
-        <FormContent />
-      </div>
-    </FormProvider>
+    <Form.Root schema={UserFeedback} defaultValues={defaultValues} onSave={onSave}>
+      <Form.Viewport>
+        <Form.Content>
+          <Form.FieldSet />
+          <Form.Submit icon='ph--paper-plane-tilt--regular' label={t('send feedback label')} disabled={disabled} />
+        </Form.Content>
+      </Form.Viewport>
+    </Form.Root>
   );
 };

package/src/components/index.ts

@@ -3,5 +3,3 @@
 //
 
 export * from './FeedbackForm';
-export * from './HelpContainer';
-export * from './ObservabilitySettings';

package/src/containers/HelpContainer/HelpContainer.tsx

@@ -0,0 +1,55 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import React, { useCallback, useState } from 'react';
+
+import { useCapability, useOperationInvoker } from '@dxos/app-framework/ui';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { runAndForwardErrors } from '@dxos/effect';
+import { useAsyncEffect } from '@dxos/react-hooks';
+import { osTranslations } from '@dxos/ui-theme';
+
+import { FeedbackForm } from '../../components';
+import { meta } from '../../meta';
+import { ObservabilityCapabilities, ObservabilityOperation, type UserFeedback } from '../../types';
+
+/** Renders the feedback form, disabling it when the feedback survey is unavailable. */
+export const HelpContainer = () => {
+  const { invokePromise } = useOperationInvoker();
+  const observability = useCapability(ObservabilityCapabilities.Observability);
+  const [feedbackAvailable, setFeedbackAvailable] = useState(false);
+
+  useAsyncEffect(
+    async (controller) => {
+      const available = await observability.isAvailable('feedback').pipe(
+        Effect.catchAll(() => Effect.succeed(false)),
+        Effect.catchAllDefect(() => Effect.succeed(false)),
+        runAndForwardErrors,
+      );
+      if (!controller.signal.aborted) {
+        setFeedbackAvailable(available);
+      }
+    },
+    [observability],
+  );
+
+  const handleSave = useCallback(
+    async (values: UserFeedback) => {
+      await invokePromise(ObservabilityOperation.CaptureUserFeedback, values);
+      await invokePromise(LayoutOperation.UpdateComplementary, { state: 'collapsed' });
+      await invokePromise(LayoutOperation.AddToast, {
+        id: `${meta.id}/feedback-success`,
+        icon: 'ph--paper-plane-tilt--regular',
+        duration: 3000,
+        title: ['feedback toast label', { ns: meta.id }],
+        description: ['feedback toast description', { ns: meta.id }],
+        closeLabel: ['close label', { ns: osTranslations }],
+      });
+    },
+    [invokePromise],
+  );
+
+  return <FeedbackForm onSave={handleSave} disabled={!feedbackAvailable} />;
+};

package/src/containers/HelpContainer/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { HelpContainer } from './HelpContainer';
+
+export default HelpContainer;

package/src/containers/ObservabilitySettings/ObservabilitySettings.tsx

@@ -0,0 +1,53 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import React from 'react';
+
+import { useOperationInvoker } from '@dxos/app-framework/ui';
+import { Input, Message, useTranslation } from '@dxos/react-ui';
+import { Settings } from '@dxos/react-ui-form';
+
+import { meta } from '../../meta';
+import { ObservabilityOperation } from '../../types';
+
+export const ObservabilitySettingsSchema = Schema.mutable(
+  Schema.Struct({
+    enabled: Schema.Boolean,
+    // TODO(wittjosiah): Separate settings for each observability feature.
+    // metrics?: boolean;
+    // telemetry?: boolean;
+    // errors?: boolean;
+  }),
+);
+
+export type ObservabilitySettingsProps = Schema.Schema.Type<typeof ObservabilitySettingsSchema>;
+
+export type ObservabilitySettingsComponentProps = {
+  settings: ObservabilitySettingsProps;
+  onSettingsChange: (fn: (current: ObservabilitySettingsProps) => ObservabilitySettingsProps) => void;
+};
+
+export const ObservabilitySettings = ({ settings }: ObservabilitySettingsComponentProps) => {
+  const { t } = useTranslation(meta.id);
+  const { invokePromise } = useOperationInvoker();
+
+  return (
+    <Settings.Root>
+      <Settings.Section title={t('settings title', { ns: meta.id })}>
+        <Message.Root valence='info' classNames=' mb-form-padding'>
+          <Message.Content>{t('observability description')}</Message.Content>
+        </Message.Root>
+        <Settings.Group>
+          <Settings.ItemInput title={t('observability enabled label')}>
+            <Input.Switch
+              checked={settings.enabled}
+              onCheckedChange={(checked) => invokePromise(ObservabilityOperation.Toggle, { state: !!checked })}
+            />
+          </Settings.ItemInput>
+        </Settings.Group>
+      </Settings.Section>
+    </Settings.Root>
+  );
+};

package/src/containers/ObservabilitySettings/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { ObservabilitySettings } from './ObservabilitySettings';
+
+export default ObservabilitySettings;

package/src/containers/index.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type ComponentType, lazy } from 'react';
+
+export { ObservabilitySettingsSchema } from './ObservabilitySettings/ObservabilitySettings';
+export type {
+  ObservabilitySettingsProps,
+  ObservabilitySettingsComponentProps,
+} from './ObservabilitySettings/ObservabilitySettings';
+
+export const HelpContainer: ComponentType<any> = lazy(() => import('./HelpContainer'));
+export const ObservabilitySettings: ComponentType<any> = lazy(() => import('./ObservabilitySettings'));

package/src/index.ts

@@ -2,8 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-export { ObservabilityCapabilities } from './capabilities';
-export { ObservabilityEvents } from './events';
+export { ObservabilityCapabilities, ObservabilityEvents } from './types';
 export * from './components';
 export * from './meta';
 export * from './ObservabilityPlugin';

package/src/meta.ts

@@ -2,10 +2,15 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type PluginMeta } from '@dxos/app-framework';
+import { type Plugin } from '@dxos/app-framework';
+import { trim } from '@dxos/util';
 
-export const meta: PluginMeta = {
+export const meta: Plugin.Meta = {
   id: 'dxos.org/plugin/observability',
   name: 'Telemetry',
+  description: trim`
+    Application observability and telemetry collection for monitoring performance and usage patterns.
+    Track metrics, logs, and traces for system health and analytics.
+  `,
   icon: 'ph--eye--regular',
 };

package/src/translations.ts

@@ -22,10 +22,10 @@ export const translations = [
         // TODO: Add link about telemetry privacy. Make it clearer that user data is not collected.
         'observability description':
           'When enabled, basic usage data will used to improve the product. This may include performance metrics, error logs, and usage data. No personally identifiable information, other than your public key, is included with this data and no private data ever leaves your devices.',
-
         'help label': 'Feedback & Support',
-        'feedback text area label': 'Feedback',
-        'feedback text area placeholder': 'Please enter your feedback, technical issue, or feature request.',
+        'feedback textarea label': 'Feedback',
+        'feedback textarea placeholder': 'Please enter your feedback, technical issue, or feature request.',
+        'include debug logs label': 'Include debug logs',
         'send feedback label': 'Send Feedback',
         'feedback toast label': 'Thank you for your feedback!',
         'feedback toast description': 'We will review your feedback and get back to you as soon as possible.',

package/src/types/capabilities.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Atom } from '@effect-atom/atom-react';
+import * as Schema from 'effect/Schema';
+
+import { Capability } from '@dxos/app-framework';
+import { type Client } from '@dxos/client';
+import { type Observability } from '@dxos/observability';
+
+import { type ObservabilitySettingsProps } from '../containers';
+import { meta } from '../meta';
+
+export namespace ObservabilityCapabilities {
+  export const Settings = Capability.make<Atom.Writable<ObservabilitySettingsProps>>(`${meta.id}/capability/settings`);
+
+  export const StateSchema = Schema.mutable(
+    Schema.Struct({
+      group: Schema.optional(Schema.String),
+      notified: Schema.optional(Schema.Boolean),
+    }),
+  );
+
+  export type State = Schema.Schema.Type<typeof StateSchema>;
+
+  export const State = Capability.make<Atom.Writable<State>>(`${meta.id}/capability/state`);
+
+  export const Observability = Capability.make<Observability.Observability>(`${meta.id}/capability/observability`);
+}
+
+// NOTE: This is cloned from the client plugin to avoid circular dependencies.
+// TODO(burdon): Figure out how to share defs.
+export const ClientCapability = Capability.make<Client>('dxos.org/plugin/client/capability/client');

package/src/types/events.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { ActivationEvent } from '@dxos/app-framework';
+import { AppActivationEvents } from '@dxos/app-toolkit';
+
+import { meta } from '../meta';
+
+export namespace ObservabilityEvents {
+  export const StateReady: ActivationEvent.ActivationEvent = AppActivationEvents.createStateEvent(meta.id);
+}
+
+// NOTE: This is cloned from the client plugin to avoid circular dependencies.
+export const ClientReadyEvent = ActivationEvent.make('dxos.org/plugin/client/event/client-ready');

package/src/types/index.ts

@@ -2,4 +2,6 @@
 // Copyright 2025 DXOS.org
 //
 
+export * from './capabilities';
+export * from './events';
 export * from './schema';

package/src/types/schema.ts

@@ -4,213 +4,81 @@
 
 import * as Schema from 'effect/Schema';
 
-import { Type } from '@dxos/echo';
+import { Capability } from '@dxos/app-framework';
+import { Format } from '@dxos/echo';
+import { Operation } from '@dxos/operation';
 
 import { meta } from '../meta';
+import { translations } from '../translations';
 
-const nonEmpty = <S extends Schema.Schema.Any>(field: string) =>
-  Schema.nonEmptyString<S>({ message: () => `Missing field: ${field}` });
-
-const maxLength = <S extends Schema.Schema.Any>(field: string, length: number) =>
-  Schema.maxLength<S>(length, { message: () => `Exceeds max length (${length}): ${field}` });
+const t = translations[0]['en-US'][meta.id];
 
 export const UserFeedback = Schema.Struct({
-  message: Schema.String.pipe(nonEmpty('Feedback'), maxLength('Feedback', 32_768)),
+  message: Format.Text.pipe(
+    Schema.nonEmptyString(),
+    Schema.maxLength(4_096),
+    Schema.annotations({
+      title: t['feedback textarea label'],
+      description: t['feedback textarea placeholder'],
+    }),
+  ),
+  includeLogs: Schema.Boolean.pipe(
+    Schema.annotations({
+      title: t['include debug logs label'],
+    }),
+    Schema.optional,
+  ),
 });
 
 export type UserFeedback = Schema.Schema.Type<typeof UserFeedback>;
 
-export namespace ObservabilityAction {
-  export class Toggle extends Schema.TaggedClass<Toggle>()(`${meta.id}/action/toggle`, {
-    input: Schema.Struct({
-      state: Schema.optional(Schema.Boolean),
-    }),
-    output: Schema.Boolean,
-  }) {}
+const OBSERVABILITY_OPERATION = `${meta.id}/operation`;
+
+/**
+ * Operations for the Observability plugin.
+ */
+export namespace ObservabilityOperation {
+  export const Toggle = Operation.make({
+    meta: {
+      key: `${OBSERVABILITY_OPERATION}/toggle`,
+      name: 'Toggle Observability',
+      description: 'Toggle observability on or off.',
+    },
+    services: [Capability.Service],
+    schema: {
+      input: Schema.Struct({
+        state: Schema.optional(Schema.Boolean),
+      }),
+      output: Schema.Boolean,
+    },
+  });
 
-  export class CaptureUserFeedback extends Schema.TaggedClass<CaptureUserFeedback>()(
-    `${meta.id}/action/capture-feedback`,
-    {
+  export const CaptureUserFeedback = Operation.make({
+    meta: {
+      key: `${OBSERVABILITY_OPERATION}/capture-feedback`,
+      name: 'Capture User Feedback',
+      description: 'Capture user feedback.',
+    },
+    services: [Capability.Service],
+    schema: {
       input: UserFeedback,
       output: Schema.Void,
     },
-  ) {}
+  });
 
-  /** Base intent for sending events. */
-  export class BaseSendEvent extends Schema.TaggedClass<BaseSendEvent>()(`${meta.id}/action/send-event`, {
-    input: Schema.Struct({
-      name: Schema.String,
-      properties: Schema.optional(Schema.Object),
-    }),
-    output: Schema.Void,
-  }) {}
-
-  /** Intent with strict types for first-party events. */
-  export class SendEvent extends Schema.TaggedClass<SendEvent>()(`${meta.id}/action/send-event`, {
-    // NOTE: Sort alphabetically by name.
-    input: Schema.Union(
-      Schema.Struct({
-        name: Schema.Literal('identity.create'),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('identity.join'),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('identity.recover'),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('identity.share'),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('navigation.activate'),
-        properties: Schema.Struct({
-          subjectId: Schema.String,
-          typename: Schema.optional(Schema.String),
-        }),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('page.load'),
-        properties: Schema.Struct({
-          loadDuration: Schema.Number,
-        }),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('plugins.toggle'),
-        properties: Schema.Struct({
-          plugin: Schema.String,
-          enabled: Schema.Boolean,
-        }),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('space.create'),
-        properties: Schema.Struct({
-          spaceId: Type.SpaceId,
-        }),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('space.join'),
-        properties: Schema.Struct({
-          spaceId: Type.SpaceId,
-        }),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('space.limit'),
-        properties: Schema.Struct({
-          spaceId: Type.SpaceId,
-        }),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('space.lock'),
-        properties: Schema.Struct({
-          spaceId: Type.SpaceId,
-        }),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('space.migrate'),
-        properties: Schema.Struct({
-          spaceId: Type.SpaceId,
-          targetVersion: Schema.optional(Schema.String),
-          version: Schema.optional(Schema.String),
-        }),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('space.schema.use'),
-        properties: Schema.Struct({
-          spaceId: Type.SpaceId,
-          typename: Schema.String,
-        }),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('space.schema.add'),
-        properties: Schema.Struct({
-          spaceId: Type.SpaceId,
-          objectId: Schema.String,
-          typename: Schema.String,
-        }),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('space.object.add'),
-        properties: Schema.Struct({
-          spaceId: Type.SpaceId,
-          objectId: Schema.String,
-          typename: Schema.optional(Schema.String),
-        }),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('space.share'),
-        properties: Schema.Struct({
-          spaceId: Type.SpaceId,
-        }),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('space.unlock'),
-        properties: Schema.Struct({
-          spaceId: Type.SpaceId,
-        }),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('threads.create'),
-        properties: Schema.Struct({
-          spaceId: Type.SpaceId,
-          threadId: Schema.String,
-        }),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('threads.delete'),
-        properties: Schema.Struct({
-          spaceId: Type.SpaceId,
-          threadId: Schema.String,
-        }),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('threads.message.add'),
-        properties: Schema.Struct({
-          spaceId: Type.SpaceId,
-          threadId: Schema.String,
-          threadLength: Schema.Number,
-          messageId: Schema.String,
-          messageLength: Schema.Number,
-        }),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('threads.message.delete'),
-        properties: Schema.Struct({
-          spaceId: Type.SpaceId,
-          threadId: Schema.String,
-          messageId: Schema.String,
-        }),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('threads.message.undo-delete'),
-        properties: Schema.Struct({
-          spaceId: Type.SpaceId,
-          threadId: Schema.String,
-          messageId: Schema.String,
-        }),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('threads.message.update'),
-        properties: Schema.Struct({
-          spaceId: Type.SpaceId,
-          messageId: Schema.String,
-          messageLength: Schema.Number,
-        }),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('threads.toggle-resolved'),
-        properties: Schema.Struct({
-          spaceId: Type.SpaceId,
-          threadId: Schema.String,
-        }),
-      }),
-      Schema.Struct({
-        name: Schema.Literal('threads.undo-delete'),
-        properties: Schema.Struct({
-          spaceId: Type.SpaceId,
-          threadId: Schema.String,
-        }),
+  export const SendEvent = Operation.make({
+    meta: {
+      key: `${OBSERVABILITY_OPERATION}/send-event`,
+      name: 'Send Event',
+      description: 'Send an observability event.',
+    },
+    services: [Capability.Service],
+    schema: {
+      input: Schema.Struct({
+        name: Schema.String.annotations({ description: 'The name of the event.' }),
+        properties: Schema.optional(Schema.Any).annotations({ description: 'Event properties.' }),
       }),
-    ),
-    output: Schema.Void,
-  }) {}
+      output: Schema.Void,
+    },
+  });
 }