@dxos/plugin-magazine 0.0.0

package/src/containers/MagazineArticle/MagazineArticle.tsx

@@ -0,0 +1,146 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useAtomValue } from '@effect-atom/atom-react';
+import React, { useCallback, useEffect, useMemo } from 'react';
+
+import { useOperationInvoker } from '@dxos/app-framework/ui';
+import { LayoutOperation, Paths } from '@dxos/app-toolkit';
+import { type AppSurface, useShowItem } from '@dxos/app-toolkit/ui';
+import { Obj, Ref } from '@dxos/echo';
+import { log } from '@dxos/log';
+import { useObject } from '@dxos/react-client/echo';
+import { Panel, useTranslation } from '@dxos/react-ui';
+import { linkedSegment, useSelection } from '@dxos/react-ui-attention';
+import { Masonry } from '@dxos/react-ui-masonry';
+import { Menu } from '@dxos/react-ui-menu';
+
+import { useVisibleMagazinePosts } from '#atoms';
+import { meta } from '#meta';
+import { FeedOperation, Magazine, Subscription } from '#types';
+
+import { MagazineTile } from './MagazineTile';
+import { useToolbar } from './useToolbar';
+
+export type MagazineArticleProps = AppSurface.ObjectArticleProps<Magazine.Magazine>;
+
+export const MagazineArticle = ({ role, subject, attendableId }: MagazineArticleProps) => {
+  const { t } = useTranslation(meta.profile.key);
+  const invoker = useOperationInvoker();
+  const [magazine] = useObject(subject);
+
+  // The toolbar owns the view-filter atom and the curate/clear handlers; the article reads `view` to
+  // filter the visible posts.
+  const { menu, viewAtom } = useToolbar({ magazine: subject });
+  const view = useAtomValue(viewAtom);
+
+  const showItem = useShowItem();
+  const id = attendableId ?? Obj.getURI(magazine);
+  const currentId = useSelection(id, 'single');
+  const db = Obj.getDatabase(magazine);
+  const posts = useVisibleMagazinePosts(subject, view);
+
+  const handleToggleStar = useCallback(
+    async (post: Subscription.Post, starred: boolean) => {
+      const subscription = await post.source?.load();
+      if (db && subscription) {
+        void Subscription.setTag(subscription, post.id, db, 'starred', !starred);
+      }
+    },
+    [db],
+  );
+
+  const handleOpen = useCallback(
+    async (post: Subscription.Post) => {
+      const subscription = await post.source?.load();
+      if (subscription && !Subscription.getReadAt(subscription, post.id)) {
+        void Subscription.setReadAt(subscription, post.id, new Date().toISOString());
+      }
+      if (post.link) {
+        void invoker
+          .invokePromise(FeedOperation.LoadPostContent, { post: Ref.make(post) })
+          .catch((err) => log.catch(err, { postLink: post.link }));
+      }
+      void showItem({
+        contextId: id,
+        selectionId: post.id,
+        companion: linkedSegment('post'),
+        path: Paths.getObjectPathFromObject(subject),
+      });
+    },
+    [id, showItem, invoker, subject],
+  );
+
+  const noPosts = posts.length === 0;
+  useEffect(() => {
+    if (noPosts) {
+      void invoker.invokePromise(LayoutOperation.UpdateCompanion, {
+        subject: linkedSegment('settings'),
+      });
+    }
+  }, [noPosts, invoker]);
+
+  const tileItems = useMemo<TileData[]>(
+    () =>
+      posts.map((post) => ({
+        id: post.id,
+        post,
+        magazine: subject,
+        current: currentId === post.id,
+        onToggleStar: handleToggleStar,
+        onOpen: handleOpen,
+      })),
+    [posts, currentId, handleOpen, handleToggleStar],
+  );
+
+  return (
+    <Panel.Root role={role}>
+      <Menu.Root {...menu} attendableId={attendableId}>
+        <Panel.Toolbar asChild>
+          <Menu.Toolbar />
+        </Panel.Toolbar>
+      </Menu.Root>
+      <Panel.Content>
+        {noPosts ? (
+          // TODO(burdon): Factor out common EmptyState component; of push into Masonry, List, etc.
+          <div className='h-full flex items-center justify-center text-subdued text-sm'>
+            {t('empty-magazine.message')}
+          </div>
+        ) : (
+          <Masonry.Root Tile={TileAdapter} minColumnWidth={20} maxColumnWidth={25}>
+            <Masonry.Content thin centered padding>
+              {/* TODO(burdon): Move items into Root. */}
+              <Masonry.Viewport classNames='py-2' items={tileItems} />
+            </Masonry.Content>
+          </Masonry.Root>
+        )}
+      </Panel.Content>
+    </Panel.Root>
+  );
+};
+
+type TileData = {
+  id: string;
+  post: Subscription.Post;
+  magazine: Magazine.Magazine;
+  current: boolean;
+  onToggleStar?: (post: Subscription.Post, starred: boolean) => void;
+  onOpen?: (post: Subscription.Post) => void;
+};
+
+const TileAdapter = ({ data }: { data: TileData | undefined; index: number }) => {
+  if (!data?.post) {
+    return null;
+  }
+
+  return (
+    <MagazineTile
+      post={data.post}
+      magazine={data.magazine}
+      current={data.current}
+      onOpen={data.onOpen}
+      onToggleStar={data.onToggleStar}
+    />
+  );
+};

package/src/containers/MagazineArticle/MagazineTile.tsx

@@ -0,0 +1,88 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { type MouseEvent, useCallback } from 'react';
+
+import { Obj } from '@dxos/echo';
+import { Card, Focus, SystemIconButton } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import { useMagazinePostData } from '#atoms';
+import { type Magazine, type Subscription } from '#types';
+
+import { formatDate } from '../../util/date';
+
+export type MagazineTileProps = {
+  post: Subscription.Post;
+  magazine: Magazine.Magazine;
+  current?: boolean;
+  onOpen?: (post: Subscription.Post) => void;
+  onToggleStar?: (post: Subscription.Post, starred: boolean) => void;
+};
+
+export const MagazineTile = ({ post, magazine, current, onToggleStar, onOpen }: MagazineTileProps) => {
+  // All per-Post derivation (snapshot, read, starred, snippet, image, feed name) happens in
+  // atom-land; this tile re-renders only when THIS post's slice changes, not when a sibling does.
+  const { post: snapshot, feedName, read, starred, snippet, imageUrl } = useMagazinePostData(post, magazine);
+
+  // `Focus.Item` calls `onCurrentChange` on click and on Enter.
+  const handleCurrentChange = useCallback(() => {
+    onOpen?.(post);
+  }, [onOpen, post]);
+
+  const handleToggleStar = useCallback(
+    (event: MouseEvent<HTMLButtonElement>) => {
+      // Prevent Focus.Item's onClick from firing the open action — clicks on the star toggle should not open the post.
+      event.stopPropagation();
+      onToggleStar?.(post, starred);
+    },
+    [onToggleStar, post, starred],
+  );
+
+  return (
+    <Focus.Item asChild current={current} onCurrentChange={handleCurrentChange}>
+      <Card.Root
+        fullWidth
+        classNames={mx('dx-hover dx-current cursor-pointer transition-opacity', read && !current && 'opacity-60')}
+      >
+        {imageUrl && (
+          <Card.Poster alt={snapshot.title ?? 'Article'} image={imageUrl} fit='cover' classNames='rounded-t-xs' />
+        )}
+        <Card.Header>
+          <Card.Block>
+            <SystemIconButton.Star
+              variant='ghost'
+              iconOnly
+              square
+              size={4}
+              active={starred}
+              onClick={handleToggleStar}
+            />
+          </Card.Block>
+          {snapshot.title ? <Card.Title classNames='line-clamp-2'>{snapshot.title}</Card.Title> : <div />}
+          <Card.Block end />
+        </Card.Header>
+        <Card.Body>
+          {snippet && (
+            <Card.Row>
+              <Card.Text variant='description' classNames='line-clamp-3'>
+                {snippet}
+              </Card.Text>
+            </Card.Row>
+          )}
+          <Card.Row>
+            <div className='grid grid-cols-[minmax(0,1fr)_auto] items-center gap-2 py-1.5 text-sm text-description overflow-hidden'>
+              <span className='truncate'>{feedName ?? ''}</span>
+              <span className='text-end shrink-0'>{formatPublished(snapshot) ?? ''}</span>
+            </div>
+          </Card.Row>
+        </Card.Body>
+      </Card.Root>
+    </Focus.Item>
+  );
+};
+
+/** Convenience: format a Post's published date the way the magazine view shows it. */
+const formatPublished = (post: Obj.Snapshot<Subscription.Post>): string | undefined =>
+  post.published ? formatDate(post.published) : undefined;

package/src/containers/MagazineArticle/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { MagazineArticle as default } from './MagazineArticle';

package/src/containers/MagazineArticle/useToolbar.tsx

@@ -0,0 +1,145 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Atom, RegistryContext, useAtomSet } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+import { useCallback, useContext, useMemo } from 'react';
+
+import { useOperationInvoker } from '@dxos/app-framework/ui';
+import { Obj, Ref } from '@dxos/echo';
+import { EffectEx } from '@dxos/effect';
+import { MenuBuilder, useMenuBuilder } from '@dxos/react-ui-menu';
+
+import { type MagazineView } from '#atoms';
+import { meta } from '#meta';
+import { FeedOperation, type Magazine } from '#types';
+
+export type UseToolbarProps = {
+  magazine: Magazine.Magazine;
+};
+
+/**
+ * Owns the magazine toolbar: the view-filter and curate-busy atoms, the Curate/Clear operation
+ * handlers, and the reactive menu action graph. The action graph reads its state — view filter,
+ * curate-busy flag, and whether the magazine has feeds — via `get` inside the builder, so it
+ * subscribes to those atoms and rebuilds whenever they change. Returns the menu props (spread into
+ * `Menu.Root`) plus `viewAtom`, which the article also reads to filter the visible posts.
+ */
+export const useToolbar = ({ magazine }: UseToolbarProps) => {
+  const invoker = useOperationInvoker();
+  const registry = useContext(RegistryContext);
+  const db = Obj.getDatabase(magazine);
+  const viewAtom = useMemo(() => Atom.make<MagazineView>('default'), []);
+  const busyAtom = useMemo(() => Atom.make(false), []);
+  const setView = useAtomSet(viewAtom);
+
+  // Curate and Clear share the busy guard: ignore re-entry while a run is in flight, flip the busy flag
+  // for the duration, then run the supplied invocation (failures surface via its own notify config).
+  const runExclusive = useCallback(
+    <A, E>(effect: Effect.Effect<A, E>) => {
+      if (registry.get(busyAtom)) {
+        return;
+      }
+      registry.set(busyAtom, true);
+      void EffectEx.runAndForwardErrors(effect.pipe(Effect.ensuring(Effect.sync(() => registry.set(busyAtom, false)))));
+    },
+    [registry, busyAtom],
+  );
+
+  const handleCurate = useCallback(
+    () =>
+      runExclusive(
+        invoker.invoke(
+          FeedOperation.CurateMagazine,
+          { magazine: Ref.make(magazine) },
+          { spaceId: db?.spaceId, notify: { error: ['curate-error.message', { ns: meta.profile.key }] } },
+        ),
+      ),
+    [runExclusive, invoker, magazine, db],
+  );
+
+  const handleClear = useCallback(
+    () =>
+      runExclusive(
+        invoker.invoke(
+          FeedOperation.ClearMagazine,
+          { magazine: Ref.make(magazine) },
+          { spaceId: db?.spaceId, notify: { error: ['clear-error.message', { ns: meta.profile.key }] } },
+        ),
+      ),
+    [runExclusive, invoker, magazine, db],
+  );
+
+  const menu = useMenuBuilder(
+    (get) => {
+      const view = get(viewAtom);
+      const busy = get(busyAtom);
+      const hasFeeds = (get(Obj.atomProperty(magazine, 'feeds')) ?? []).length > 0;
+      // Curate runs the magazine's Routine, so it is unavailable until that Routine exists.
+      const hasRoutine = Boolean(get(Obj.atomProperty(magazine, 'instructions')));
+      // Curate is disabled while busy or until there is at least one feed; the tooltip explains why.
+      const curateLabel = !hasFeeds ? 'no-feeds.label' : busy ? 'refreshing-magazine.label' : 'curate.label';
+
+      return (
+        MenuBuilder.make()
+          // Single-select filter: `value` is the active child id; `'default'` matches neither, so both
+          // toggles read as off. Re-clicking the active toggle returns to `'default'`.
+          .group(
+            'view',
+            {
+              label: ['view-filter.label', { ns: meta.profile.key }],
+              variant: 'toggleGroup',
+              selectCardinality: 'single',
+              value: view,
+            },
+            (group) => {
+              group.action(
+                'starred',
+                {
+                  label: ['only-starred.label', { ns: meta.profile.key }],
+                  icon: view === 'starred' ? 'ph--star--fill' : 'ph--star--regular',
+                },
+                () => setView(view === 'starred' ? 'default' : 'starred'),
+              );
+              group.action(
+                'archived',
+                {
+                  label: ['show-archived.label', { ns: meta.profile.key }],
+                  icon: 'ph--archive--regular',
+                },
+                () => setView(view === 'archived' ? 'default' : 'archived'),
+              );
+            },
+          )
+          // `gap` is a flexible spacer that pushes Clear + Curate to the trailing edge.
+          .separator('gap')
+          .action(
+            'clear',
+            {
+              label: ['clear-magazine.label', { ns: meta.profile.key }],
+              icon: 'ph--broom--regular',
+              iconOnly: true,
+              disabled: busy,
+            },
+            handleClear,
+          )
+          .action(
+            'curate',
+            {
+              label: [curateLabel, { ns: meta.profile.key }],
+              icon: busy ? 'ph--circle-notch--regular' : 'ph--sparkle--regular',
+              iconClassNames: busy ? 'animate-spin' : undefined,
+              iconOnly: true,
+              disabled: busy || !hasFeeds || !hasRoutine,
+            },
+            handleCurate,
+          )
+          .build()
+      );
+    },
+    [magazine, viewAtom, busyAtom, setView, handleClear, handleCurate],
+  );
+
+  return { menu, viewAtom };
+};

package/src/containers/PostArticle/PostArticle.stories.tsx

@@ -0,0 +1,117 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import React from 'react';
+
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { type Client } from '@dxos/client';
+import { type Space } from '@dxos/client/echo';
+import { Filter, Tag } from '@dxos/echo';
+import { ClientPlugin, initializeIdentity } from '@dxos/plugin-client/testing';
+import { SpacePlugin } from '@dxos/plugin-space/testing';
+import { StorybookPlugin, corePlugins } from '@dxos/plugin-testing';
+import { useQuery, useSpaces } from '@dxos/react-client/echo';
+import { Loading, withLayout } from '@dxos/react-ui/testing';
+import { Text } from '@dxos/schema';
+
+import { translations } from '#translations';
+import { Subscription } from '#types';
+
+import { MagazinePlugin } from '../../MagazinePlugin';
+import { PostArticle } from './PostArticle';
+
+const SAMPLE_MARKDOWN = `# Local-first software
+
+> "You own your data, in spite of the cloud." — Ink & Switch
+
+Local-first apps put the user's data on their own device, syncing through a
+decentralized substrate rather than a central server. That shift unlocks several
+properties that cloud apps struggle to deliver:
+
+## Why it matters
+
+- **No spinners.** Reads and writes hit local storage, so latency is sub-millisecond.
+- **Offline by default.** The network is an enhancement, not a requirement.
+- **Longevity.** Your data survives the vendor — no lock-in, no shutdown risk.
+
+## A small example
+
+\`\`\`ts
+const space = await client.spaces.create();
+const note = space.db.add(Obj.make(Note, { title: 'Hello' }));
+\`\`\`
+
+See the [original essay](https://www.inkandswitch.com/local-first/) for the full
+list of seven ideals, including real-time collaboration and end-to-end privacy.
+`;
+
+const DefaultStory = () => {
+  const spaces = useSpaces();
+  const space = spaces[spaces.length - 1];
+  const posts = useQuery(space?.db, Filter.type(Subscription.Post));
+  const post = posts[0];
+  if (!post) {
+    return <Loading />;
+  }
+
+  return <PostArticle role='article' subject={post} attendableId='story' />;
+};
+
+// `PostArticle` calls `useOperationInvoker` (for the star/archive/mark-unread toolbar actions), so
+// the story must render under a plugin manager that provides the OperationInvoker capability — a
+// bare `withClientProvider` throws "Missing PluginManagerContext".
+const seedSpace = ({ client }: { client: Client }) =>
+  Effect.gen(function* () {
+    yield* initializeIdentity(client);
+    const space = (yield* Effect.promise(() => client.spaces.create())) as Space;
+    yield* Effect.promise(() => space.waitUntilReady());
+
+    // Content/imageUrl no longer live on the Post object — they belong on
+    // `Subscription.contentFeed` / `Subscription.postState`. PostContent falls
+    // back to `description` when no fetched body is available, so the sample
+    // markdown is stashed there for the story.
+    space.db.add(
+      Subscription.makePost({
+        title: 'Local-first software: a primer',
+        link: 'https://www.inkandswitch.com/local-first/',
+        author: 'Martin Kleppmann',
+        published: new Date().toISOString(),
+        guid: 'local-first-primer',
+        description: SAMPLE_MARKDOWN,
+      }),
+    );
+    yield* Effect.promise(() => space.db.flush());
+  });
+
+const meta: Meta<typeof DefaultStory> = {
+  title: 'plugins/plugin-magazine/containers/PostArticle',
+  render: DefaultStory,
+  decorators: [
+    withLayout({ layout: 'fullscreen' }),
+    withPluginManager({
+      plugins: [
+        ...corePlugins(),
+        ClientPlugin({
+          types: [Subscription.Subscription, Subscription.Post, Tag.Tag, Text.Text],
+          onClientInitialized: seedSpace,
+        }),
+        SpacePlugin({}),
+        StorybookPlugin({}),
+        MagazinePlugin(),
+      ],
+    }),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/containers/PostArticle/PostArticle.tsx

@@ -0,0 +1,140 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Atom, RegistryContext } from '@effect-atom/atom-react';
+import React, { useCallback, useContext, useEffect, useMemo, useRef } from 'react';
+
+import { useOperationInvoker } from '@dxos/app-framework/ui';
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { Filter, Obj, Ref } from '@dxos/echo';
+import { log } from '@dxos/log';
+import { useObject, useQuery } from '@dxos/react-client/echo';
+import { Panel } from '@dxos/react-ui';
+import { getParentId, isLinkedSegment } from '@dxos/react-ui-attention';
+
+import { usePostContentAtom } from '#atoms';
+import { PostContent } from '#components';
+import { meta } from '#meta';
+import { FeedOperation } from '#types';
+import { Subscription } from '#types';
+
+import { PostToolbar } from './PostToolbar';
+
+export type PostArticleProps = AppSurface.ObjectArticleProps<Subscription.Post>;
+
+export const PostArticle = ({ role, subject, attendableId }: PostArticleProps) => {
+  // When shown as a companion the `attendableId` is a linked segment, but attention lives on the
+  // parent plank — resolve to the parent so the toolbar reads as attended (active).
+  const toolbarAttendableId = attendableId && isLinkedSegment(attendableId) ? getParentId(attendableId) : attendableId;
+  const { invokePromise } = useOperationInvoker();
+  const registry = useContext(RegistryContext);
+  const [post] = useObject(subject);
+  const db = Obj.getDatabase(post);
+  const subscription = post.source?.target;
+  const { id } = post;
+  const postContent = usePostContentAtom(subject);
+
+  // Lazily fetch full article content the first time this Post is shown — covers
+  // entry points that bypass MagazineArticle's `handleOpen` (deep-link, agent surface,
+  // restored attention). LoadPostContent is idempotent (no-op if `content` already
+  // populated or `link` missing), so a unique guard per Post id is enough to keep us
+  // from re-firing on every render.
+  const requestedContentFor = useRef<string | undefined>(undefined);
+  useEffect(() => {
+    if (requestedContentFor.current === id) {
+      return;
+    }
+    if (!post.link || postContent) {
+      return;
+    }
+    requestedContentFor.current = id;
+    void invokePromise(FeedOperation.LoadPostContent, { post: Ref.make(subject) }).catch((err) =>
+      log.catch(err, { postLink: post.link }),
+    );
+  }, [subject, post, post.link, postContent, invokePromise, id]);
+
+  // Reactive lookup of the source feed name. `post.feed?.target?.name` only renders
+  // synchronously when the ref is already resolved; querying feeds via useQuery means
+  // the meta line updates as soon as the feed object is loaded into the space.
+  const allFeeds = useQuery(db, Filter.type(Subscription.Subscription));
+  const feedName = useMemo(() => {
+    const dxn = post.source?.uri;
+    if (!dxn) {
+      return undefined;
+    }
+    return allFeeds.find((feed) => Obj.getURI(feed) === dxn)?.name;
+  }, [post.source, allFeeds]);
+
+  const handleOpenOriginal = useCallback(() => {
+    if (post.link) {
+      window.open(post.link, '_blank', 'noopener,noreferrer');
+    }
+  }, [post.link]);
+
+  const handleMarkUnread = useCallback(() => {
+    if (subscription) {
+      Subscription.setReadAt(subscription, id, undefined);
+    }
+  }, [subscription, id]);
+
+  // Value-setters (not toggles): the toolbar reads the current star/archive state reactively via
+  // `get` and passes the desired next value, so these don't need to subscribe to the current state.
+  const handleSetArchived = useCallback(
+    (value: boolean) => {
+      if (db && subscription) {
+        void Subscription.setTag(subscription, id, db, 'archived', value);
+      }
+    },
+    [db, subscription, id],
+  );
+
+  const handleSetStarred = useCallback(
+    (value: boolean) => {
+      if (db && subscription) {
+        void Subscription.setTag(subscription, id, db, 'starred', value);
+      }
+    },
+    [db, subscription, id],
+  );
+
+  // Re-fetch the article body from the source via the LoadPostContent operation with `force`, so the
+  // fetch/extraction/storage logic lives in one place (the operation) rather than inline here. Appends
+  // a fresh content entry to the subscription's contentFeed; the reverse-ref lookup picks the newest.
+  // `refreshing` is an atom so the toolbar subscribes to it via `get` rather than via React deps.
+  const refreshingAtom = useMemo(() => Atom.make(false), []);
+  const handleRefresh = useCallback(async () => {
+    if (!post.link || registry.get(refreshingAtom)) {
+      return;
+    }
+    registry.set(refreshingAtom, true);
+    try {
+      // Failures surface as a toast via `notify`; invokePromise resolves with `{ error }`, never throws.
+      await invokePromise(
+        FeedOperation.LoadPostContent,
+        { post: Ref.make(subject), force: true },
+        { notify: { error: ['refresh-content-error.message', { ns: meta.profile.key }] } },
+      );
+    } finally {
+      registry.set(refreshingAtom, false);
+    }
+  }, [registry, refreshingAtom, subject, post.link, invokePromise]);
+
+  return (
+    <Panel.Root role={role}>
+      <PostToolbar
+        post={subject}
+        refreshingAtom={refreshingAtom}
+        attendableId={toolbarAttendableId}
+        onSetStarred={handleSetStarred}
+        onSetArchived={handleSetArchived}
+        onMarkUnread={handleMarkUnread}
+        onRefresh={() => void handleRefresh()}
+        onOpenOriginal={handleOpenOriginal}
+      />
+      <Panel.Content asChild>
+        <PostContent post={subject} metadata={feedName ? [feedName] : undefined} />
+      </Panel.Content>
+    </Panel.Root>
+  );
+};