@dxos/plugin-deck 0.8.4-main.4a85c3132b → 0.8.4-main.4f23b4e393

package/src/components/Plank/Plank.tsx

@@ -1,302 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { useFocusFinders } from '@fluentui/react-tabster';
-import React, {
-  type KeyboardEvent,
-  type PropsWithChildren,
-  memo,
-  useCallback,
-  useLayoutEffect,
-  useMemo,
-  useRef,
-} from 'react';
-
-import { Surface, useOperationInvoker } from '@dxos/app-framework/ui';
-import { LayoutOperation } from '@dxos/app-toolkit';
-import { useAppGraph } from '@dxos/app-toolkit/ui';
-import { debounce } from '@dxos/async';
-import { type Node, useNode } from '@dxos/plugin-graph';
-import { ATTENDABLE_PATH_SEPARATOR, useAttentionAttributes } from '@dxos/react-ui-attention';
-import { StackItem, railGridHorizontal } from '@dxos/react-ui-stack';
-import { mainIntrinsicSize, mx } from '@dxos/ui-theme';
-
-import { useCompanions, useDeckState, useMainSize, useSelectedCompanion } from '../../hooks';
-import { parseEntryId } from '../../layout';
-import { DeckOperation, type DeckSettingsProps, type LayoutMode, type ResolvedPart } from '../../types';
-
-import { PlankError, PlankErrorFallback } from './PlankError';
-import { PlankHeading } from './PlankHeading';
-import { PlankLoading } from './PlankLoading';
-
-const UNKNOWN_ID = 'unknown_id';
-
-//
-// Plank
-//
-
-export type PlankProps = Pick<PlankComponentProps, 'layoutMode' | 'part' | 'path' | 'order' | 'active' | 'settings'> & {
-  id?: string;
-  companionVariant?: string;
-};
-
-// TODO(burdon): Factor out conditional rendering.
-//   Remove this wrapper component and render the entire set of planks in the deck with conditional visibility
-//   to obviate mounting and unmounting when switching between solo and companion mode?
-// NOTE(thure, in reply): Whether any surface should be rendered and hidden is a performance matter — remember that
-//  article surfaces contain full experiences, so being able to unmount them will yield relatively large performance
-//  benefits. I think where we anticipate users will definitely want to quickly switch between showing and hiding entire
-//  articles, over the (again probably large) performance benefit that unmounting them would confer, we can mount and
-//  hide them, but I think that scenario in its most unambiguous form is probably rare. You could extrapolate
-//  the scenario to include all "potential" planks such as companions, which we could keep mounted and hidden, but I
-//  don't think the resulting performance would be acceptable. I think the real issue is "perceived performance" which
-//  has mitigations that are in between mounting and un-mounting since both of those have tradeoffs; we may need one or more
-//  "partially-mounted" experiences, like loading skeletons at the simple end, or screenshots of "sleeping" planks at
-//  the advanced end.
-
-/**
- * A Plank is the main container for surfaces within a Deck.
- * It may be paired with a companion plank that enables the user to select one of multiple companion surfaces.
- */
-export const Plank = memo(({ id = UNKNOWN_ID, companionVariant, ...props }: PlankProps) => {
-  const { graph } = useAppGraph();
-  const node = useNode(graph, id);
-  const companions = useCompanions(id);
-  const { companionId } = useSelectedCompanion(companions, companionVariant);
-  const resolvedCompanionId = companionVariant ? companionId : undefined;
-  const currentCompanion = companions.find(({ id }) => id === resolvedCompanionId);
-  const hasCompanion = !!(resolvedCompanionId && currentCompanion);
-
-  return (
-    <PlankContainer
-      solo={props.part === 'solo'}
-      companion={hasCompanion}
-      encapsulate={!!props.settings?.encapsulatedPlanks}
-    >
-      <PlankComponent
-        id={id}
-        node={node}
-        companioned={hasCompanion ? 'primary' : undefined}
-        companions={hasCompanion ? [] : companions}
-        {...props}
-        {...(props.part === 'solo' ? { part: 'solo-primary' } : {})}
-      />
-      {hasCompanion && (
-        <PlankComponent
-          id={resolvedCompanionId}
-          node={currentCompanion}
-          primary={node}
-          companions={companions}
-          companioned='companion'
-          {...props}
-          {...(props.part === 'solo' ? { part: 'solo-companion' } : { order: (props.order ?? 0) + 1 })}
-        />
-      )}
-    </PlankContainer>
-  );
-});
-
-//
-// PlankContainer
-//
-
-type PlankContainerProps = PropsWithChildren<{ solo: boolean; companion: boolean; encapsulate: boolean }>;
-
-const PlankContainer = ({ children, solo, companion, encapsulate }: PlankContainerProps) => {
-  const sizeAttrs = useMainSize();
-  if (!solo) {
-    return children;
-  }
-
-  // TODO(burdon): Make resizable.
-  return (
-    <div
-      role='none'
-      data-popover-collision-boundary={true}
-      className={mx(
-        'absolute inset-(--main-spacing) grid',
-        encapsulate && 'border border-separator rounded-sm overflow-hidden',
-        companion && 'grid-cols-[6fr_4fr]', // TODO(burdon): Resize.
-        railGridHorizontal,
-        mainIntrinsicSize,
-      )}
-      {...sizeAttrs}
-    >
-      {children}
-    </div>
-  );
-};
-
-//
-// PlankComponent
-//
-
-type PlankComponentProps = {
-  layoutMode: LayoutMode;
-  id: string;
-  part: ResolvedPart;
-  path?: string[];
-  order?: number;
-  active?: string[];
-  companioned?: 'primary' | 'companion';
-  node?: Node.Node;
-  primary?: Node.Node;
-  companions?: Node.Node[];
-  settings?: DeckSettingsProps;
-};
-
-const PlankComponent = memo(
-  ({
-    layoutMode,
-    id,
-    part,
-    path,
-    order,
-    active,
-    companioned,
-    node,
-    primary,
-    companions,
-    settings,
-  }: PlankComponentProps) => {
-    const { invokePromise } = useOperationInvoker();
-    const { state, deck } = useDeckState();
-    const { popoverAnchorId, scrollIntoView } = state;
-    const { findFirstFocusable } = useFocusFinders();
-    const canResize = layoutMode === 'deck';
-
-    const attentionAttrs = useAttentionAttributes(primary?.id ?? id);
-    const index = active ? active.findIndex((entryId) => entryId === id) : 0;
-    const length = active?.length ?? 1;
-    const canIncrementStart = active && index !== undefined && index > 0 && length !== undefined && length > 1;
-    const canIncrementEnd = active && index !== undefined && index < length - 1 && length !== undefined;
-
-    const rootElement = useRef<HTMLDivElement | null>(null);
-
-    const { variant } = parseEntryId(id);
-    const sizeKey = `${id.split('+')[0]}${variant ? `${ATTENDABLE_PATH_SEPARATOR}${variant}` : ''}`;
-    const size = deck.plankSizing[sizeKey] as number | undefined;
-
-    const handleSizeChange = useCallback(
-      debounce((nextSize: number) => {
-        return invokePromise(DeckOperation.UpdatePlankSize, { id: sizeKey, size: nextSize });
-      }, 200),
-      [invokePromise, sizeKey],
-    );
-
-    // TODO(thure): Tabster's focus group should handle moving focus to Main, but something is blocking it.
-    const handleKeyDown = useCallback((event: KeyboardEvent) => {
-      if (event.target === event.currentTarget) {
-        switch (event.key) {
-          case 'Escape':
-            rootElement.current?.closest('main')?.focus();
-            break;
-          case 'Enter':
-            rootElement.current && findFirstFocusable(rootElement.current)?.focus();
-            break;
-        }
-      }
-    }, []);
-
-    useLayoutEffect(() => {
-      if (scrollIntoView === id) {
-        layoutMode === 'deck' && rootElement.current?.scrollIntoView({ behavior: 'smooth', inline: 'center' });
-        // Clear the scroll into view state once it has been actioned.
-        void invokePromise(LayoutOperation.ScrollIntoView, { subject: undefined });
-      }
-    }, [id, scrollIntoView, layoutMode, invokePromise]);
-
-    const isSolo = layoutMode.startsWith('solo') && part === 'solo';
-    const isAttendable =
-      (layoutMode.startsWith('solo') && part.startsWith('solo')) || (layoutMode === 'deck' && part === 'deck');
-
-    const sizeAttrs = useMainSize();
-
-    const data = useMemo(
-      () =>
-        node && {
-          attendableId: id,
-          subject: node.data,
-          companionTo: primary?.data,
-          properties: node.properties,
-          variant,
-          path,
-          popoverAnchorId,
-        },
-      [node, node?.data, node?.properties, path, popoverAnchorId, primary?.data, variant],
-    );
-
-    // TODO(wittjosiah): Change prop to accept a component.
-    const placeholder = useMemo(() => <PlankLoading />, []);
-
-    const Root = part.startsWith('solo') ? 'article' : StackItem.Root;
-    const fullscreen = layoutMode === 'solo--fullscreen';
-    const className = mx(
-      'dx-attention-surface relative dx-focus-ring-inset-over-all dx-density-coarse',
-      isSolo && 'absolute inset-0',
-      isSolo && mainIntrinsicSize,
-      railGridHorizontal,
-      part.startsWith('solo') && 'grid',
-      part.startsWith('solo-') && 'grid-rows-subgrid row-span-2 min-w-0',
-      fullscreen && 'grid-rows-1',
-      part === 'deck' && (companioned === 'companion' ? 'border-separator! border-e' : 'border-separator! border-x'),
-      part === 'solo-companion' && 'border-separator! border-s',
-      settings?.encapsulatedPlanks &&
-        !part.startsWith('solo') &&
-        'mx-(--main-spacing) border-separator! border rounded-sm overflow-hidden',
-    );
-
-    return (
-      <Root
-        ref={rootElement}
-        data-testid='deck.plank'
-        data-popover-collision-boundary={true}
-        tabIndex={0}
-        {...(part.startsWith('solo')
-          ? ({ ...sizeAttrs, className } as any)
-          : {
-              item: { id },
-              size,
-              onSizeChange: handleSizeChange,
-              classNames: className,
-              order,
-              role: 'article',
-            })}
-        {...(isAttendable ? attentionAttrs : {})}
-        onKeyDown={handleKeyDown}
-      >
-        {node ? (
-          <>
-            {!fullscreen && (
-              <PlankHeading
-                id={id}
-                part={part.startsWith('solo-') ? 'solo' : part}
-                node={node}
-                layoutMode={layoutMode}
-                deckEnabled={settings?.enableDeck}
-                canIncrementStart={canIncrementStart}
-                canIncrementEnd={canIncrementEnd}
-                popoverAnchorId={popoverAnchorId}
-                primaryId={primary?.id}
-                companioned={companioned}
-                companions={companions}
-              />
-            )}
-            <Surface.Surface
-              key={node.id}
-              role='article'
-              data={data}
-              limit={1}
-              fallback={PlankErrorFallback}
-              placeholder={placeholder}
-            />
-          </>
-        ) : (
-          <PlankError id={id} part={part} />
-        )}
-        {canResize && <StackItem.ResizeHandle />}
-      </Root>
-    );
-  },
-);

package/src/components/fragments.ts

@@ -1,19 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { mx } from '@dxos/ui-theme';
-
-// TODO(burdon): Move to these as dx-components?
-
-/** @private */
-export const soloInlinePadding =
-  'ps-[calc(env(safe-area-inset-left)+.25rem)] pe-[calc(env(safe-area-inset-right)+.25rem)]';
-
-const sidebarToggleStyles = 'h-(--dx-rail-item) w-(--dx-rail-item) absolute bottom-2 z-[1] !bg-deck-surface lg:hidden';
-
-/** @private */
-export const fixedSidebarToggleStyles = mx(sidebarToggleStyles, 'left-2');
-
-/** @private */
-export const fixedComplementarySidebarToggleStyles = mx(sidebarToggleStyles, 'right-2');

package/src/containers/Banner/Banner.tsx

@@ -1,5 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-export { Banner } from '../../components';

package/src/containers/Banner/index.ts

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

package/src/containers/DeckSettings/DeckSettings.tsx

@@ -1,113 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import React from 'react';
-
-import { Input, Select, useTranslation } from '@dxos/react-ui';
-import { Settings } from '@dxos/react-ui-form';
-
-import { meta } from '../../meta';
-import {
-  type DeckSettingsProps,
-  type NewPlankPositioning,
-  NewPlankPositions,
-  OverScrollToProps,
-  type Overscroll,
-} from '../../types';
-
-const isSocket = !!(globalThis as any).__args;
-
-export type DeckSettingsComponentProps = {
-  settings: DeckSettingsProps;
-  onSettingsChange: (fn: (current: DeckSettingsProps) => DeckSettingsProps) => void;
-};
-
-export const DeckSettings = ({ settings, onSettingsChange }: DeckSettingsComponentProps) => {
-  const { t } = useTranslation(meta.id);
-
-  return (
-    <Settings.Root>
-      <Settings.Section title={t('settings title', { ns: meta.id })}>
-        <Settings.Group>
-          <Settings.ItemInput title={t('settings enable deck label')}>
-            <Input.Switch
-              checked={settings.enableDeck}
-              onCheckedChange={(checked) => onSettingsChange((s) => ({ ...s, enableDeck: checked }))}
-            />
-          </Settings.ItemInput>
-          <Settings.ItemInput title={t('settings encapsulated planks label')}>
-            <Input.Switch
-              checked={settings.encapsulatedPlanks ?? false}
-              onCheckedChange={(checked) => onSettingsChange((s) => ({ ...s, encapsulatedPlanks: checked }))}
-            />
-          </Settings.ItemInput>
-          <Settings.ItemInput title={t('select new plank positioning label')}>
-            <Select.Root
-              disabled={!settings.enableDeck}
-              value={settings.newPlankPositioning ?? 'start'}
-              onValueChange={(value) =>
-                onSettingsChange((s) => ({ ...s, newPlankPositioning: value as NewPlankPositioning }))
-              }
-            >
-              <Select.TriggerButton placeholder={t('select new plank positioning placeholder')} />
-              <Select.Portal>
-                <Select.Content>
-                  <Select.Viewport>
-                    {NewPlankPositions.map((position) => (
-                      <Select.Option key={position} value={position}>
-                        {t(`settings new plank position ${position} label`)}
-                      </Select.Option>
-                    ))}
-                  </Select.Viewport>
-                  <Select.Arrow />
-                </Select.Content>
-              </Select.Portal>
-            </Select.Root>
-          </Settings.ItemInput>
-          <Settings.ItemInput title={t('settings overscroll label')}>
-            <Select.Root
-              disabled={!settings.enableDeck}
-              value={settings.overscroll ?? 'none'}
-              onValueChange={(value) => onSettingsChange((s) => ({ ...s, overscroll: value as Overscroll }))}
-            >
-              <Select.TriggerButton placeholder={t('select overscroll placeholder')} />
-              <Select.Portal>
-                <Select.Content>
-                  <Select.Viewport>
-                    {OverScrollToProps.map((option) => (
-                      <Select.Option key={option} value={option}>
-                        {t(`settings overscroll ${option} label`)}
-                      </Select.Option>
-                    ))}
-                  </Select.Viewport>
-                  <Select.Arrow />
-                </Select.Content>
-              </Select.Portal>
-            </Select.Root>
-          </Settings.ItemInput>
-          <Settings.ItemInput title={t('settings enable statusbar label')}>
-            <Input.Switch
-              checked={settings.enableStatusbar}
-              onCheckedChange={(checked) => onSettingsChange((s) => ({ ...s, enableStatusbar: checked }))}
-            />
-          </Settings.ItemInput>
-          <Settings.ItemInput title={t('settings show hints label')}>
-            <Input.Switch
-              checked={settings.showHints}
-              onCheckedChange={(checked) => onSettingsChange((s) => ({ ...s, showHints: checked }))}
-            />
-          </Settings.ItemInput>
-          {!isSocket && (
-            <Settings.ItemInput title={t('settings native redirect label')}>
-              <Input.Switch
-                checked={settings.enableNativeRedirect}
-                onCheckedChange={(checked) => onSettingsChange((s) => ({ ...s, enableNativeRedirect: checked }))}
-              />
-            </Settings.ItemInput>
-          )}
-        </Settings.Group>
-      </Settings.Section>
-    </Settings.Root>
-  );
-};

package/src/containers/DeckSettings/index.ts

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

package/src/types/capabilities.ts

@@ -1,33 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { type Atom } from '@effect-atom/atom-react';
-import * as Effect from 'effect/Effect';
-
-import { Capabilities, Capability } from '@dxos/app-framework';
-import { invariant } from '@dxos/invariant';
-
-import { meta } from '../meta';
-import { type DeckEphemeralStateProps, type DeckSettingsProps, type DeckState, type DeckStateProps } from '../types';
-
-export namespace DeckCapabilities {
-  export const Settings = Capability.make<Atom.Writable<DeckSettingsProps>>(`${meta.id}/capability/settings`);
-
-  /** Persisted state (stored in KVS/localStorage). */
-  export const State = Capability.make<Atom.Writable<DeckStateProps>>(`${meta.id}/capability/state`);
-
-  /** Transient/ephemeral state (not persisted). */
-  export const EphemeralState = Capability.make<Atom.Writable<DeckEphemeralStateProps>>(
-    `${meta.id}/capability/ephemeral-state`,
-  );
-
-  /** Get the current active deck from state. */
-  export const getDeck = (): Effect.Effect<DeckState, Error, Capability.Service> =>
-    Effect.gen(function* () {
-      const state = yield* Capabilities.getAtomValue(State);
-      const deck = state.decks[state.activeDeck];
-      invariant(deck, `Deck not found: ${state.activeDeck}`);
-      return deck;
-    });
-}

package/src/types/events.ts

@@ -1,21 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { type ActivationEvent } from '@dxos/app-framework';
-import { AppActivationEvents } from '@dxos/app-toolkit';
-
-import { meta } from '../meta';
-
-import { DeckCapabilities } from './capabilities';
-
-export namespace DeckEvents {
-  export const StateReady: ActivationEvent.ActivationEvent = AppActivationEvents.createStateEvent(
-    `${meta.id}/state-ready`,
-  );
-
-  /** Fired when DeckSettings capability is ready. */
-  export const SettingsReady: ActivationEvent.ActivationEvent = AppActivationEvents.createSettingsEvent(
-    DeckCapabilities.Settings.identifier,
-  );
-}

package/src/util/overscroll.ts

@@ -1,69 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import type { CSSProperties } from 'react';
-
-/**
- * ┌────────────────────────────────────────────────────────────────────────────────────────────────────┐
- * | Overscroll Padding Calculation for Centering Planks on Screen.                                     │
- * ├────────────────────────────────────────────────────────────────────────────────────────────────────┤
- * │ NOTE(Zan): I found the way you calculate the overscroll padding to center a plank on the screen    │
- * │ at the edges of the scroll context a bit confusing, so I've diagrammed it here.                    │
- * │                                                                                                    │
- * │ Multiple Planks:                                                                                   │
- * │ ───────────────                                                                                    │
- * | Use the following overscroll padding calculation centering the boundary planks on the SCREEN.      │
- * │                                                                                                    │
- * │ Left Padding:                           Right Padding:                                             │
- * │ ┌───┬────┬──────────────────┬──────┐    ┌──────┬──────────────────┬────┬───┐                       │
- * │ │   │████│     Ideal        │      │    │      │      Ideal       │████│   │                       │
- * │ │ S │█PL█│     first        │      │    │      │      last        │█PR█│ C │                       │
- * │ │   │████│     plank        │      │    │      │      plank       │████│   │                       │
- * │ └───┴────┴──────────────────┴──────┘    └──────┴──────────────────┴────┴───┘                       │
- * │ <--------- screen width ----------->    <---------- screen width ---------->                       │
- * │                                                                                                    │
- * │ PL = ((screen width - Plank Width) / 2) - S                                                        │
- * │ PR = ((screen width - Plank Width) / 2) - C                                                        │
- * │                                                                                                    │
- * │ S  = Sidebar width                     C  = Complementary sidebar width                            │
- * │ PL = Padding Left                      PR = Padding Right                                          │
- * │                                                                                                    │
- * │ Single Plank:                                                                                      │
- * │ ─────────────                                                                                      │
- * │ For a single plank we use the following overscroll padding calculation to center the plank in      │
- * │ the content area:                                                                                  │
- * │                                                                                                    │
- * │ ┌───┬───────────────────────┬───┬───────────────────────┬───┐                                      │
- * │ │   │███████████████████████│   │███████████████████████│   │                                      │
- * │ │ S │█████ Left Padding ████│ P │████ Right Padding ████│ C │                                      │
- * │ │   │███████████████████████│   │███████████████████████│   │                                      │
- * │ └───┴───────────────────────┴───┴───────────────────────┴───┘                                      │
- * │ <------------------------ screen width --------------------->                                      │
- * │                                                                                                    │
- * │ Left/Right Padding Width = (screen width - S - P - C) / 2                                          │
- * │                                                                                                    │
- * │ S = Sidebar width (may be 0)                                                                       │
- * │ P = Plank width (centered)                                                                         │
- * │ C = Complementary sidebar width (may be 0)                                                         │
- * └────────────────────────────────────────────────────────────────────────────────────────────────────┘
- */
-export const calculateOverscroll = (
-  planksCount: number,
-): Pick<CSSProperties, 'paddingInlineStart' | 'paddingInlineEnd'> | undefined => {
-  if (!planksCount) {
-    return { paddingInlineStart: 0, paddingInlineEnd: 0 };
-  }
-  if (planksCount === 1) {
-    const overscrollPadding =
-      'max(0px, calc(((100dvw - var(--dx-main-sidebar-width) - var(--dx-main-complementary-width) - (var(--dx-main-content-first-width) + 1px)) / 2)))';
-    return { paddingInlineStart: overscrollPadding, paddingInlineEnd: overscrollPadding };
-  } else {
-    return {
-      paddingInlineStart:
-        'max(0px, calc(((100dvw - (var(--dx-main-content-first-width) + 1px)) / 2) - var(--dx-main-sidebar-width)))',
-      paddingInlineEnd:
-        'max(0px, calc(((100dvw - (var(--dx-main-content-last-width) + 1px)) / 2) - var(--dx-main-complementary-width)))',
-    };
-  }
-};