@terrafirmagreg-team/mdx 1.2.7 → 1.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terrafirmagreg-team/mdx",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "type": "module",
   "description": "MDX/markdown pipeline",
   "license": "LGPL-3.0-only",
@@ -23,7 +23,7 @@
     "@fumadocs/story": "^1.5.3",
     "@fumari/stf": "^1.1.2",
     "@terrafirmagreg-team/translate": "^1.2.8",
-    "@terrafirmagreg-team/ui": "^1.2.9",
+    "@terrafirmagreg-team/ui": "^1.2.10",
     "fumadocs-core": "16.17.10",
     "fumadocs-docgen": "^3.2.0",
     "fumadocs-twoslash": "^4.0.4",

package/src/components/story-fields.tsx

@@ -15,8 +15,17 @@ import {
   SelectValue,
 } from '@terrafirmagreg-team/ui/components/ui/select';
 import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
-import { X } from 'lucide-react';
-import { useState } from 'react';
+import { Pin, PinOff, X } from 'lucide-react';
+import { createContext, useContext, useState } from 'react';
+
+export const PinnedContext = createContext<{
+  pinned: ReadonlySet<string>;
+  toggle: (name: string) => void;
+} | null>(null);
+
+export function usePinned() {
+  return useContext(PinnedContext);
+}
 
 function resolveNode(node: TypeNode, value: unknown): TypeNode {
   if (node.type === 'intersection') return resolveNode(node.intersection, value);
@@ -234,6 +243,8 @@ function Field({
   const [value, setValue] = useFieldValue([name]);
   const resolved = resolveNode(node, value);
   const members = selectMembers(resolved);
+  const pinnedCtx = usePinned();
+  const isPinned = pinnedCtx?.pinned.has(name) ?? false;
 
   let editor: React.ReactNode;
   if (members) {
@@ -275,6 +286,26 @@ function Field({
       <span className="hidden w-24 shrink-0 truncate px-2 font-mono text-xs text-fd-muted-foreground/70 @3xl:block">
         {typeToString(resolved)}
       </span>
+      {pinnedCtx && !required && (
+        <button
+          type="button"
+          aria-label={`${isPinned ? 'Unpin' : 'Pin'} ${name}`}
+          title={
+            isPinned
+              ? 'Unpin — reset with preset'
+              : 'Pin — keep value across presets'
+          }
+          onClick={() => pinnedCtx.toggle(name)}
+          className={cn(
+            'me-1 flex size-6 shrink-0 items-center justify-center rounded-md hover:bg-fd-accent',
+            isPinned
+              ? 'text-fd-primary'
+              : 'text-fd-muted-foreground hover:text-fd-foreground',
+          )}
+        >
+          {isPinned ? <PinOff className="size-3" /> : <Pin className="size-3" />}
+        </button>
+      )}
       {!required && (
         <button
           type="button"

package/src/components/story-panel.tsx

@@ -6,8 +6,9 @@ import {
   useStoryArgs,
   type WithControlProps,
 } from '@fumadocs/story';
-import { StoryFields } from './story-fields';
-import { remarkFor, tweakControls } from '../lib/story-remark';
+import { useDataEngine } from '@fumari/stf';
+import { PinnedContext, StoryFields, usePinned } from './story-fields';
+import { directiveMeta, remarkFor, tweakControls } from '../lib/story-remark';
 import { highlightRemark } from '../lib/remark-highlight';
 import { useCopyButton } from '@terrafirmagreg-team/ui/hooks/use-copy-button';
 import { Check, Clipboard } from 'lucide-react';
@@ -22,22 +23,34 @@ import {
   Component,
   createElement,
   useMemo,
+  useState,
   type ErrorInfo,
   type ReactNode,
 } from 'react';
-import { CircleAlert, RotateCcw } from 'lucide-react';
+import {
+  ChevronLeft,
+  ChevronRight,
+  CircleAlert,
+  RotateCcw,
+} from 'lucide-react';
 
 function RemarkHint() {
   const { displayName, preset, variant } = useStory();
   const args = useStoryArgs();
+  const suppressed =
+    directiveMeta(displayName ?? '')?.remark === false;
   const text = useMemo(
-    () => remarkFor(displayName ?? 'component', args, preset?.controls, variant),
-    [displayName, args, preset, variant],
+    () =>
+      suppressed
+        ? ''
+        : remarkFor(displayName ?? 'component', args, preset?.controls, variant),
+    [suppressed, displayName, args, preset, variant],
   );
   const tokens = useMemo(() => highlightRemark(text), [text]);
   const { checked, onClick } = useCopyButton(() =>
     navigator.clipboard.writeText(text),
   );
+  if (suppressed) return null;
   return (
     <div className="relative border-t">
       <pre className="overflow-x-auto px-4 py-2.5 pe-9 font-mono text-xs leading-relaxed text-fd-muted-foreground whitespace-pre-wrap">
@@ -93,34 +106,83 @@ class PreviewBoundary extends Component<
   }
 }
 
+function useApplyVariant() {
+  const { setVariant } = useStory();
+  const engine = useDataEngine();
+  const pinned = usePinned();
+  return (value: string) => {
+    const keep = new Map(
+      [...(pinned?.pinned ?? [])].map(
+        (name) =>
+          [name, (engine.getData() as Record<string, unknown>)[name]] as const,
+      ),
+    );
+    setVariant(value);
+    for (const [name, value] of keep) {
+      if (value === undefined) engine.delete([name]);
+      else if (!engine.update([name], value)) engine.init([name], value);
+    }
+  };
+}
+
 function VariantSelect() {
-  const { presets, variant, setVariant } = useStory();
+  const { presets, variant } = useStory();
+  const applyVariant = useApplyVariant();
+  const index = presets.findIndex((p) => p.variant === variant);
+  const step = (delta: number) => {
+    const next =
+      presets[(index + delta + presets.length) % presets.length];
+    if (next) applyVariant(next.variant);
+  };
+  const stepClass =
+    'rounded-md p-1.5 text-fd-muted-foreground hover:bg-fd-accent hover:text-fd-foreground';
   return (
-    <Select value={variant} onValueChange={(v) => v && setVariant(v)}>
-      <SelectTrigger className="h-7 w-auto max-w-64 gap-1.5 border-0 bg-transparent px-2 text-xs hover:bg-fd-accent focus:ring-0 focus-visible:ring-2">
-        <span className="text-fd-muted-foreground">Variant</span>
-        <SelectValue className="truncate font-medium" />
-      </SelectTrigger>
-      <SelectContent align="end">
-        {presets.map((item) => (
-          <SelectItem
-            key={item.variant}
-            value={item.variant}
-            className="text-xs"
-          >
-            {item.variant}
-          </SelectItem>
-        ))}
-      </SelectContent>
-    </Select>
+    <div className="flex items-center gap-0.5">
+      <button
+        type="button"
+        aria-label="Previous variant"
+        title="Previous variant"
+        onClick={() => step(-1)}
+        className={stepClass}
+      >
+        <ChevronLeft className="size-3.5" />
+      </button>
+      <Select value={variant} onValueChange={(v) => v && applyVariant(v)}>
+        <SelectTrigger className="h-7 w-auto max-w-64 gap-1.5 border-0 bg-transparent px-2 text-xs hover:bg-fd-accent focus:ring-0 focus-visible:ring-2">
+          <span className="text-fd-muted-foreground">Variant</span>
+          <SelectValue className="truncate font-medium" />
+        </SelectTrigger>
+        <SelectContent align="end">
+          {presets.map((item) => (
+            <SelectItem
+              key={item.variant}
+              value={item.variant}
+              className="text-xs"
+            >
+              {item.variant}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+      <button
+        type="button"
+        aria-label="Next variant"
+        title="Next variant"
+        onClick={() => step(1)}
+        className={stepClass}
+      >
+        <ChevronRight className="size-3.5" />
+      </button>
+    </div>
   );
 }
 
 function Content() {
-  const { presets, displayName, preset, variant, setVariant, Component } =
+  const { presets, displayName, preset, variant, Component } =
     useStory();
+  const applyVariant = useApplyVariant();
   const args = useStoryArgs();
-  const reset = () => setVariant(variant);
+  const reset = () => applyVariant(variant);
   return (
     <div className="not-prose overflow-hidden rounded-xl border bg-fd-card text-fd-card-foreground">
       {(displayName || presets.length > 1) && (
@@ -172,9 +234,25 @@ export function DocsWithControl({ presets, ...rest }: WithControlProps) {
       })),
     [presets, rest.displayName],
   );
+  const [pinned, setPinned] = useState<ReadonlySet<string>>(new Set());
+  const pinApi = useMemo(
+    () => ({
+      pinned,
+      toggle: (name: string) =>
+        setPinned((prev) => {
+          const next = new Set(prev);
+          if (next.has(name)) next.delete(name);
+          else next.add(name);
+          return next;
+        }),
+    }),
+    [pinned],
+  );
   return (
     <StoryProvider {...rest} presets={tweaked}>
-      <Content />
+      <PinnedContext.Provider value={pinApi}>
+        <Content />
+      </PinnedContext.Provider>
     </StoryProvider>
   );
 }

package/src/lib/story-remark.ts

@@ -13,6 +13,7 @@ export type DirectiveMeta = {
   props?: string[];
   solo?: boolean;
   paired?: boolean;
+  remark?: boolean;
   descriptions?: Record<string, string>;
   raw?: string;
   variants?: Record<string, Partial<DirectiveMeta>>;
@@ -397,6 +398,27 @@ const DIRECTIVE_META: Record<string, DirectiveMeta> = {
       Display: { raw: '$$e = mc^2$$' },
     },
   },
+  og: {
+    remark: false,
+    props: ['url', 'section', 'dataset', 'slug', 'lang', 'version'],
+    descriptions: {
+      url: 'Page or image.png URL — overrides the fields below',
+      section: 'Site section the page belongs to',
+      dataset: 'Dataset id within the section',
+      slug: 'Page path inside the dataset, e.g. getting-started/install',
+      lang: 'Content language of the rendered card',
+      version: 'Dataset version pin, e.g. 0.13.18',
+    },
+  },
+  site: {
+    remark: false,
+    props: ['view', 'section', 'links'],
+    descriptions: {
+      view: 'What to show',
+      section: 'Limit the listing to one section',
+      links: 'URLs to preview in the links view (JSON array)',
+    },
+  },
 };
 
 export function directiveMeta(key: string): DirectiveMeta | undefined {