@mosetta/editor 0.0.0-stage → 0.0.29

package/tiles/content/blockPage.tsx

@@ -0,0 +1,379 @@
+// THE BLOCK'S PAGE (ADR-0060) — a story of Storybook's kind, for a block of a distribution: the
+// block LIVE on a stage, its real settings form always open beside it, and its VARIANTS — the
+// states its editor facet declares — as a wall of live specimens; one clicked goes into the stage.
+//
+// The PLAYGROUND is the form's own store (blockVariants.ts) behind a door of its own: the form is
+// mounted with a parent container that holds that store and the project's config, nothing else —
+// no references to bind, no media to upload, no document. Whatever is turned here stays here —
+// unless taken away: "Copy block" puts the block, as it stands, on the editor's clipboard (a paste
+// on a page places it), "Copy as JSON" hands the developer what to paste into `variants`.
+//
+// The stage, the form and every specimen are mounted applications (ADR-0034), the way the picker's
+// preview and the settings popover are: the same root, the same `previewServices`.
+import { useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import { DI_CONTAINER_TOKEN, DiContainer } from '@mosetta/di';
+import { EDITOR_PROJECT_CONFIG_TOKEN, SETTINGS_DRAFT_TOKEN, useComponent, useDi } from '@mosetta/react';
+import { TILES_HOLDER_TOKEN } from '@mosetta/runtime/client';
+import type { IMountPreview } from '@mosetta/runtime/client';
+import type { ICatalogEntry, IDistributionEntry } from '@mosetta/content';
+import { editorReferenceOf, previewMountFor, previewRootOf } from './componentPreview';
+import type { IComponentFacet, IEditorFacet } from './componentPreview';
+import { hostedPage, hostFallbackOf, loadModule } from './mountedTree';
+import type { IMountSpec } from './mountedTree';
+import { formRootOf } from './formRoot';
+import { useFeedProjectConfig } from './projectConfig';
+import { useMountedTree } from './useMountedTree';
+import { useSeen } from './scaledStage';
+import { atOwnVersion, framed, frameOf, PlaygroundDraft, specimensOf, variantSource } from './blockVariants';
+import { serializeBlocks } from './editingClipboard';
+import { noticesOf } from './editingNotices';
+import type { ISpecimen, IVariantFrame } from './blockVariants';
+import { FORM_HOST_CLASS, SETTINGS_TABS, shownTab, tabsIn } from '../canvas/settingsTabs';
+import type { TSettingsTab } from '../canvas/settingsTabs';
+import './blockPage.css';
+
+/** how long "Copied" stands on the button */
+const COPIED_MS = 1600;
+
+/** what went to the clipboard last: the block (to paste on a page), or its settings as code */
+type TCopied = 'block' | 'variant' | null;
+
+type TFacets
+  = | { readonly status: 'looking' }
+  | { readonly status: 'failed' }
+  | { readonly status: 'ready'; readonly editor: IEditorFacet | undefined; readonly defaults: Record<string, unknown> };
+
+/** the block's two facets: what its editor declares, and its default settings */
+function useBlockFacets(component: ICatalogEntry): TFacets {
+  const holder = useDi(TILES_HOLDER_TOKEN);
+  const [facets, setFacets] = useState<TFacets>({ status: 'looking' });
+  useEffect(() => {
+    let alive = true;
+    void (async () => {
+      try {
+        const [editor, block] = await Promise.all([
+          component.hasEditor ? loadModule(holder, editorReferenceOf(component.id)) : Promise.resolve(undefined),
+          loadModule(holder, component.id),
+        ]);
+        const defaults = (block?.module as IComponentFacet | undefined)?.defaultSettings?.() ?? {};
+        const facet = editor?.module as IEditorFacet | undefined;
+        if (alive) setFacets({ status: 'ready', editor: facet ? atOwnVersion(facet, component.id) : undefined, defaults });
+      } catch {
+        if (alive) setFacets({ status: 'failed' });
+      }
+    })();
+    return () => {
+      alive = false;
+    };
+  }, [holder, component.id, component.hasEditor]);
+  return facets;
+}
+
+/** the block, holding what it holds, in its frame, as the root mounts it (`fallback`: hostFallbackOf) */
+function specimenSpec(root: string, frame: IVariantFrame | null, reference: string, specimen: Pick<ISpecimen, 'settings' | 'children'>, preview: IMountPreview, fallback: string): IMountSpec {
+  return { rootReference: root, tree: hostedPage(root, framed(frame, reference, specimen), fallback), preview };
+}
+
+/**
+ * One variant, live, in a card of the wall — at its own size, as a page would show it (a scaled
+ * button is no button); mounted once in sight; a click takes it to the stage.
+ */
+function VariantCard({ specimen, spec, picked, onPick }: { specimen: ISpecimen; spec: IMountSpec; picked: boolean; onPick: () => void }) {
+  const cardRef = useRef<HTMLDivElement>(null);
+  const seen = useSeen(cardRef);
+  const { ref: stage, failed } = useMountedTree(seen ? spec : null);
+  return (
+    <div ref={cardRef}
+         className={`block-page__variant${picked ? ' block-page__variant--picked' : ''}`}
+         role="button"
+         tabIndex={0}
+         aria-pressed={picked}
+         data-test-id="block-variant"
+         data-variant={specimen.name}
+         data-picked={picked || undefined}
+         onClick={onPick}
+         onKeyDown={(e) => {
+           if (e.key === 'Enter' || e.key === ' ') {
+             e.preventDefault();
+             onPick();
+           }
+         }}>
+      <div className="block-page__variant-head">
+        <span className="block-page__variant-name">{specimen.name}</span>
+        {specimen.description ? <span className="block-page__variant-description">{specimen.description}</span> : null}
+      </div>
+      <div className="block-page__variant-view">
+        {failed ? <div className="block-page__note">Could not render this variant</div> : null}
+        <div ref={stage}
+             className="block-page__variant-stage" />
+      </div>
+    </div>
+  );
+}
+
+/**
+ * The block's settings form, always open — the popover's own frame, tabs and all, around the form
+ * mounted behind the playground's door.
+ */
+function PlaygroundSettings({ name, form, hasEditor, failed, changed, onReset, onCopyBlock, onCopyVariant, copied }: {
+  name: string;
+  form: React.MutableRefObject<HTMLDivElement | null>;
+  hasEditor: boolean;
+  failed: boolean;
+  changed: boolean;
+  onReset: () => void;
+  onCopyBlock: () => void;
+  /** the developer's copy: the settings as JSON, an entry of the facet's `variants` */
+  onCopyVariant: () => void;
+  /** which copy just went to the clipboard — its button says so for a moment */
+  copied: TCopied;
+}) {
+  const bodyRef = useRef<HTMLDivElement>(null);
+  const [tabs, setTabs] = useState<readonly TSettingsTab[]>([]);
+  const [wished, setWished] = useState<TSettingsTab>('main');
+  const tab = shownTab(tabs, wished);
+  // which tabs the form's sections fill, as the mounted form arrives and changes
+  useLayoutEffect(() => {
+    const body = bodyRef.current;
+    if (!body) return undefined;
+    const look = () => {
+      const found = tabsIn(body);
+      setTabs((prev) => (prev.join('|') === found.join('|') ? prev : found));
+    };
+    look();
+    const view = body.ownerDocument.defaultView;
+    const watch = view?.MutationObserver ? new view.MutationObserver(look) : null;
+    watch?.observe(body, { subtree: true, childList: true });
+    return () => watch?.disconnect();
+  }, []);
+  return (
+    <aside className="block-page__settings"
+           data-test-id="block-settings">
+      <div className="block-page__settings-head">
+        <span className="block-page__settings-name">{name}</span>
+        <span className="block-page__settings-note">Playground · nothing is saved</span>
+      </div>
+      {tabs.length > 1 ? (
+        <div className="block-page__tabs"
+             role="tablist"
+             aria-label="Settings">
+          {SETTINGS_TABS.filter((entry) => tabs.includes(entry.id)).map((entry) => (
+            <button key={entry.id}
+                    type="button"
+                    role="tab"
+                    className={`block-page__tab${entry.id === tab ? ' block-page__tab--on' : ''}`}
+                    data-test-id="block-settings-tab"
+                    data-tab={entry.id}
+                    aria-selected={entry.id === tab}
+                    onClick={() => setWished(entry.id)}>
+              {entry.label}
+            </button>
+          ))}
+        </div>
+      ) : null}
+      <div ref={bodyRef}
+           className="block-page__settings-body"
+           data-settings-tab={tab}>
+        {!hasEditor ? <div className="block-page__note">The block has no settings form</div> : null}
+        {failed ? <div className="block-page__note">Could not render the block’s settings</div> : null}
+        <div ref={form}
+             className={FORM_HOST_CLASS}
+             data-test-id="block-settings-form" />
+      </div>
+      <div className="block-page__settings-foot">
+        <div className="block-page__settings-actions">
+          <button type="button"
+                  className="block-page__action"
+                  data-test-id="block-reset"
+                  disabled={!changed}
+                  onClick={onReset}>
+            Reset
+          </button>
+          <button type="button"
+                  className="block-page__action block-page__action--main"
+                  data-test-id="block-copy-block"
+                  title="Copy the block as it stands here — paste it on a page (Ctrl+V)"
+                  onClick={onCopyBlock}>
+            {copied === 'block' ? 'Copied' : 'Copy block'}
+          </button>
+        </div>
+        {/* for the block's DEVELOPER: a small link under the buttons — data, not a block to paste */}
+        <button type="button"
+                className="block-page__json"
+                data-test-id="block-copy-variant"
+                title="These settings as JSON — an entry of `variants` in the block's .editor.tsx. To paste on a page, use Copy block"
+                onClick={onCopyVariant}>
+          {copied === 'variant' ? 'Copied' : 'Copy as JSON'}
+        </button>
+      </div>
+    </aside>
+  );
+}
+
+export function BlockPage({ component, distribution, components, libraryRoot, onBack }: {
+  component: ICatalogEntry;
+  distribution: IDistributionEntry;
+  components: readonly ICatalogEntry[];
+  /** a root module of the block's own library, when it ships one */
+  libraryRoot: string | undefined;
+  onBack: () => void;
+}) {
+  const self = useComponent().reference;
+  const di = useDi(DI_CONTAINER_TOKEN);
+  // the project's config, for a form that reads it (i18n: which languages) — fed before the door is made
+  useFeedProjectConfig();
+  const facets = useBlockFacets(component);
+  const editor = facets.status === 'ready' ? facets.editor : undefined;
+  const defaults = facets.status === 'ready' ? facets.defaults : null;
+  const specimens = useMemo(() => (defaults ? specimensOf(component.id, editor, defaults) : []), [component.id, editor, defaults]);
+  const [picked, setPicked] = useState(0);
+  const current = specimens[picked] as ISpecimen | undefined;
+
+  // THE PLAYGROUND: the form's store, behind a door of its own
+  const [draft] = useState(() => new PlaygroundDraft({}));
+  const [door] = useState(() => {
+    const own = new DiContainer();
+    own.registerValueOfToken(SETTINGS_DRAFT_TOKEN, draft);
+    if (di.hasByToken(EDITOR_PROJECT_CONFIG_TOKEN)) own.registerValueOfToken(EDITOR_PROJECT_CONFIG_TOKEN, di.getByToken(EDITOR_PROJECT_CONFIG_TOKEN));
+    return own;
+  });
+  const settings = useSyncExternalStore(draft.subscribe, draft.snapshot, draft.snapshot);
+  // the variant picked goes into the playground — before anything reads it: the form is mounted
+  // only once it holds the block's settings
+  const [primed, setPrimed] = useState(false);
+  useLayoutEffect(() => {
+    if (!current) return;
+    draft.reset(current.settings);
+    setPrimed(true);
+  }, [current, draft]);
+
+  // what fails to render is said in the editor's words, at the editor's own version
+  const fallback = hostFallbackOf(self);
+  const declared = typeof editor?.preview === 'object' ? editor.preview.reference : undefined;
+  const root = declared ?? libraryRoot ?? previewRootOf(self);
+  const preview = useMemo(() => previewMountFor(editor, editor?.previewServices), [editor]);
+  const frame = useMemo(() => frameOf(component.id, editor), [component.id, editor]);
+  const stageSpec = useMemo(
+    () => (primed && current ? specimenSpec(root, frame, component.id, { settings, children: current.children }, preview, fallback) : null),
+    [primed, current, root, frame, component.id, settings, preview, fallback],
+  );
+  const { ref: stage, failed: stageFailed } = useMountedTree(stageSpec);
+  const variantSpecs = useMemo(
+    () => specimens.map((specimen) => specimenSpec(root, frame, component.id, specimen, preview, fallback)),
+    [specimens, root, frame, component.id, preview, fallback],
+  );
+
+  const formRoot = useMemo(() => formRootOf(components, component.id, self), [components, component.id, self]);
+  const formSpec = useMemo(() => (primed && component.hasEditor
+    ? {
+      rootReference: formRoot,
+      tree: hostedPage(formRoot, [{ id: 'playground-form', reference: editorReferenceOf(component.id), settings: { placement: 'settings' }, children: [] }], fallback),
+    }
+    : null), [primed, component.hasEditor, component.id, formRoot, fallback]);
+  const { ref: form, failed: formFailed } = useMountedTree(formSpec, door);
+
+  const stageFrame = useRef<HTMLElement>(null);
+  const changed = current !== undefined && JSON.stringify(settings) !== JSON.stringify(current.settings);
+  const [copied, setCopied] = useState<TCopied>(null);
+  useEffect(() => {
+    if (!copied) return undefined;
+    const timer = setTimeout(() => setCopied(null), COPIED_MS);
+    return () => clearTimeout(timer);
+  }, [copied]);
+  const notices = noticesOf(di);
+  // a browser may refuse the page its clipboard — said, not swallowed
+  const refused = () => notices?.show('refuse', 'The browser did not let the page write the clipboard');
+  // the BLOCK, as it stands here, in the editor's own clipboard envelope — a paste on a page puts
+  // it there (renumbered), the way a block copied from another page arrives
+  const copyBlock = () => {
+    if (!current) return;
+    const block = { id: 'copied-block', reference: component.id, settings, children: [...current.children] };
+    void navigator.clipboard?.writeText(serializeBlocks([block])).then(() => {
+      setCopied('block');
+      notices?.show('copy', 'Copied the block — paste it on a page');
+    }, refused);
+  };
+  // …and its settings as JSON, for the block's developer: an entry of the facet's `variants`
+  const copyVariant = () => {
+    if (!defaults || !current) return;
+    const text = variantSource(changed || picked === 0 ? 'New variant' : current.name, settings, defaults);
+    void navigator.clipboard?.writeText(text).then(() => setCopied('variant'), refused);
+  };
+
+  return (
+    <div className="block-page"
+         data-test-id="block-page"
+         data-component={component.id}
+         data-block-page={facets.status}>
+      <div className="block-page__header">
+        <button type="button"
+                className="block-page__back"
+                data-test-id="block-page-back"
+                onClick={onBack}>← {distribution.title}</button>
+        <div className="block-page__title-row">
+          {component.iconUrl ? <img className="block-page__icon"
+                                    src={component.iconUrl}
+                                    alt=""
+                                    draggable={false} /> : null}
+          <h1 className="block-page__title">{component.reference.name}</h1>
+          <span className="block-page__meta">{`${component.reference.namespace}@${component.reference.version}`}</span>
+        </div>
+      </div>
+      {facets.status === 'failed' ? <div className="block-page__note">Could not load the block</div> : null}
+      <div className="block-page__main">
+        <section ref={stageFrame}
+                 className="block-page__stage-frame">
+          <div className="block-page__stage-head">
+            <span className="block-page__stage-name"
+                  data-test-id="block-stage-variant">{current?.name ?? '…'}</span>
+            {changed ? <span className="block-page__changed"
+                             data-test-id="block-changed">changed</span> : null}
+            {current?.description ? <span className="block-page__stage-description">{current.description}</span> : null}
+          </div>
+          <div className="block-page__stage-view">
+            {stageFailed ? <div className="block-page__note">Could not render the block</div> : null}
+            <div ref={stage}
+                 className="block-page__stage"
+                 data-test-id="block-stage" />
+          </div>
+        </section>
+        <PlaygroundSettings name={component.reference.name}
+                            form={form}
+                            hasEditor={component.hasEditor}
+                            failed={formFailed}
+                            changed={changed}
+                            onReset={() => current && draft.reset(current.settings)}
+                            onCopyBlock={copyBlock}
+                            onCopyVariant={copyVariant}
+                            copied={copied} />
+        {specimens.length ? (
+          <section className="block-page__variants-frame">
+            <h2 className="block-page__variants-title">
+              Variants
+              <span className="block-page__variants-count">{specimens.length}</span>
+            </h2>
+            {specimens.length === 1 ? (
+              <p className="block-page__variants-hint">
+                The block declares no variants of its own. Its editor side can list them — see “Copy as JSON”.
+              </p>
+            ) : null}
+            <div className="block-page__variants">
+              {specimens.map((specimen, index) => (
+                <VariantCard key={specimen.name}
+                             specimen={specimen}
+                             spec={variantSpecs[index]}
+                             picked={index === picked}
+                             onPick={() => {
+                               if (index === picked) draft.reset(specimen.settings);
+                               setPicked(index);
+                               // the stage is where the pick shows: into sight, if it is not
+                               stageFrame.current?.scrollIntoView?.({ block: 'nearest', behavior: 'smooth' });
+                             }} />
+              ))}
+            </div>
+          </section>
+        ) : null}
+      </div>
+    </div>
+  );
+}

package/tiles/content/blockPicker.css

@@ -0,0 +1,215 @@
+/* The block picker (blockPicker.tsx): a search on top, the blocks below — folded by provider while
+   the search is empty, one ranked list while it is not. */
+.block-picker {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  font-family: ui-sans-serif, system-ui, sans-serif;
+  font-size: var(--mosetta-wb-font);
+}
+
+/* the search field wrapper takes the input's place in the column; the input fills it. Scoped
+   under the picker: the shared field's own rule (`.search-field { flex: 1 }`, searchField.css)
+   comes along in every module that uses it, and whichever sheet loads last would win a tie —
+   stretching the field to fill the picker, the search adrift in the middle */
+.block-picker > .block-picker__search-field {
+  flex: none;
+  margin: 0 8px 6px;
+}
+
+.block-picker__search {
+  flex: none;
+  box-sizing: border-box;
+  height: calc(var(--mosetta-wb-icon-box) + 4px);
+  margin: 0;
+  padding: 0 8px;
+  border: 1px solid #d4d4d8;
+  border-radius: 6px;
+  outline: none;
+  background: #ffffff;
+  color: #27272a;
+  font: inherit;
+  font-size: var(--mosetta-wb-font-sm);
+}
+
+.block-picker__search:focus {
+  border-color: #2563eb;
+}
+
+.block-picker__list,
+.block-picker__leaves {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.block-picker__list {
+  min-height: 0;
+  overflow-y: auto;
+}
+
+/* One branch per distribution, at the version on offer — and a button, because it folds. A whole
+   provider is a lot of rows to scroll past when the block you want is in the next one. Its version
+   stands beside the button: a choice, once several are deployed (ADR-0061). */
+.block-picker__branch-head {
+  display: flex;
+  align-items: center;
+  padding-right: 8px;
+}
+
+.block-picker__branch-head:hover {
+  background: #f4f4f5;
+}
+
+.block-picker__branch-title {
+  display: flex;
+  flex: 1;
+  min-width: 0;
+  align-items: center;
+  gap: 4px;
+  padding: 3px 10px;
+  border: 0;
+  background: none;
+  color: #3f3f46;
+  font: inherit;
+  font-weight: 600;
+  text-align: left;
+  cursor: pointer;
+}
+
+
+/* points down when the branch is open, right when it is folded — the fold is the state, the
+   chevron only reports it */
+.block-picker__chevron {
+  display: flex;
+  width: calc(var(--mosetta-wb-icon-sm) - 2px);
+  height: calc(var(--mosetta-wb-icon-sm) - 2px);
+  align-items: center;
+  justify-content: center;
+  color: #a1a1aa;
+  transform: rotate(90deg);
+  transition: transform 120ms ease;
+}
+
+.block-picker__branch[data-collapsed] .block-picker__chevron {
+  transform: rotate(0deg);
+}
+
+.block-picker__chevron svg {
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+
+.block-picker__item {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  min-height: 26px;
+  padding: 2px 10px 2px 24px;
+  cursor: pointer;
+}
+
+/* the ranked list has no branches to indent under */
+.block-picker__list > .block-picker__item {
+  padding-left: 10px;
+}
+
+/* the active row — under the pointer, or walked to with the arrows; Enter inserts it. The green
+   of the place waiting in the preview: the row answers in that place's colour */
+.block-picker__item--active {
+  background: rgb(16 185 129 / 22%);
+}
+
+/* nowhere to insert (a docked palette with no place picked): the rows only show */
+.block-picker__item--inert {
+  cursor: default;
+}
+
+.block-picker__item--inert.block-picker__item--active {
+  background: #f4f4f5;
+}
+
+/* a row's picture — the block's icon, before its name: found by shape and colour first */
+.block-picker__icon {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  width: 18px;
+  height: 18px;
+  border-radius: 5px;
+}
+
+.block-picker__icon svg {
+  width: 100%;
+  height: 100%;
+}
+
+.block-picker__icon--initial {
+  background: #e4e4e7;
+  color: #52525b;
+  font-size: 10px;
+  font-weight: 700;
+}
+
+/* the branch: its distribution's icon and title; its namespace and version, quieter, beside */
+.block-picker__branch-icon {
+  flex: none;
+  width: 16px;
+  height: 16px;
+  margin-right: 2px;
+  border-radius: 4px;
+}
+
+.block-picker__branch-id {
+  flex: none;
+  color: #a1a1aa;
+  font-size: var(--mosetta-wb-font-2xs);
+  font-weight: 400;
+}
+
+.block-picker__version {
+  flex: none;
+  max-width: 120px;
+  padding: 0 2px;
+  border: 1px solid #e4e4e7;
+  border-radius: 4px;
+  background: #ffffff;
+  color: #52525b;
+  font: inherit;
+  font-size: var(--mosetta-wb-font-2xs);
+}
+
+.block-picker__name {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  color: #18181b;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.block-picker__name mark {
+  padding: 0;
+  border-radius: 2px;
+  color: inherit;
+  background: #fde68a;
+}
+
+/* flat, a row says which provider it comes from — the branch it would have folded under */
+.block-picker__branch-tag {
+  flex: none;
+  color: #a1a1aa;
+  font-size: var(--mosetta-wb-font-2xs);
+}
+
+.block-picker__note {
+  padding: 6px 10px;
+  color: #a1a1aa;
+}
+
+.block-picker__error {
+  padding: 6px 10px;
+  color: #b00;
+}